xil_set_data_supply_routine(3)

NAME

xil_set_data_supply_routine - Set the routine that will be used to fill in the storage for an image

SYNOPSIS

#include <xil/xil.h>

void xil_set_data_supply_routine(XilImage image,

XilDataSupplyFuncPtr supply_ptr,
void∗ user_args);

DESCRIPTION

It is not always possible to provide a description of the entire image’s storage. For example, tiles may be located across the network or in a file whose data cannot be memory mapped (for example, a compressed image file). In these cases, it is more efficient to provide the tile data to XIL on demand. So, only one tile is loaded into memory at a time. An additional benefit is that only those tiles that are actually needed get loaded.

XIL supports this demand-based supply by allowing the application to specify a "data supply routine" for an image. When an XIL operation needs data for a tile of the image, XIL calls the routine to obtain the data. The routine is only called when there is no data associated with a tile. The first time a tile from the image is needed, the application’s routine is called to provide data. From that point on, the data remains under XIL control as if the storage had been set.

To set the "data supply routine" for an image, the application calls xil_set_data_supply_routine ().

The prototype for the "data supply routine" is:

int app_data_supply_routine(XilImage image,

XilStorage storage,
unsigned int x,
unsigned int y,
unsigned int xsize,
unsigned int ysize,
void∗ user_args);

The image is included as an argument in the event that the same data supply routine is used for multiple images. The image should only be used as an identifier.

The user provides the data to the image through the storage object argument. The routine must call the appropriate storage functions, such as xil_storage_set_data (3), xil_storage_set_pixel_stride (3), and xil_storage_set_scanline_stride (3) in order to set the image data.

The x and y arguments indicate the upper left coordinate of the data portion required.

The xsize and ysize will most likely be the tile xsize and tile ysize, but as the image may have been re-imported, the programmer will have no way to access the tile size at the time of the callback.

user_args are available to provide any specific data that the routine may require, and will match the user_args provided in the xil_set_data_supply_routine () for the image.

EXAMPLES

A program that uses a data supply routine to provide data to an XIL image for processing. The supply data is stored in a contiguous buffer, 256 x 256. The image tile size is initially set to 64 x 64, but may change before the data supply routine is called. The supply data is a a buffer of 4 banded (RGBA) BYTE data that represents an RGB image.

struct arg_info {
unsigned int width;
unsigned int height;
unsigned int nbands;
};
XilSystemState state;
XilImage        tile_image;
struct arg_info myarg_info;

state = xil_open();
xil_state_set_default_tiling_mode(state, XIL_TILING);
tile_image = xil_create(state, 256, 256, nbands, XIL_BYTE);
xil_export(tile_image);
xil_set_tilesize(tile_image, 64, 64);
xil_import(tile_image,TRUE);

/∗
∗ myarg_info holds the image information
∗/
myarg_info.width = width;
myarg_info.height = height;
myarg_info.nbands = nbands;
xil_set_data_supply_routine(tile_image, myapp_supply_routine,
                            (void∗)&myarg_info);
/∗
∗ Run program that uses tile_image as it would any other image
∗/
xil_destroy(tile_image);
xil_close(state);
}
/∗
∗ The XilDataSupplyFuncPtr
∗ used in a callback to fill in image tiles
∗ We’re assuming that the source data is already memory
∗ mapped and referenced by a pointer global_mmap_ptr
∗/
int
myapp_supply_routine(XilImage     image,
                     XilStorage   storage,
                     unsigned int x,
                     unsigned int y,
                     unsigned int xsize,
                     unsigned int ysize,
                     void        ∗myArgs)
{
    struct arg_info∗ argptr;
    unsigned int   width;
    unsigned int   height;
    unsigned int   bands;
    Xil_unsigned8∗ dataptr;
    unsigned int   scanline_stride;
    unsigned int   pixel_stride;
     /∗
     ∗ Remember - you can’t call any XIL functions on the
     ∗ image in this routine. It is purely for identification!
     ∗ So pick up the passed in image particulars
     ∗/
    argptr = (struct arg_info∗)myArgs;
    width = argptr->width;
    height = argptr->height;
    bands = argptr->nbands;
     /∗
     ∗ Example file data is pixel sequential, so
     ∗ band stride is always 1 and you only need to
     ∗ set storage for the 0th band.
     ∗ In this example our data is RGBARGBARGBA...
     ∗ with the A an unused band of a 3 band BYTE image
     ∗ The image is a contiguous 256x256 memory buffer,
     ∗ but we’re filling in for requested blocks.
     ∗/
    pixel_stride = 4;
    xil_storage_set_pixel_stride(storage,0,pixel_stride);
     scanline_stride = pixel_stride ∗ 256;
    xil_storage_set_scanline_stride(storage,0, scanline_stride);
     /∗
     ∗ Now go mmap the data for this image starting at x,y
     ∗ and of size xsize, ysize
     ∗/
    dataptr = go_mmap_data(image, x, y, xsize, ysize);
    xil_storage_set_data(storage, 0, dataptr);
    return XIL_SUCCESS;
}

NOTES

The user must not call any other XIL operations on the image while in the callback in order to avoid deadlock.

After the callback has been called for a particular part of the image, the user may not access that data again without calling xil_export(3) and one of the other storage access routines such as xil_get_tile_storage(3).

Museum