xil_export(3)

NAME

xil_export, xil_import, xil_get_exported − move an image from XIL to application space, or from application to XIL space, or determine whether an image is exported

SYNOPSIS

#include <xil/xil.h>

int xil_export ( XilImage image);

void xil_import ( XilImage image,

Xil_boolean change_flag);

int xil_get_exported ( XilImage image);

DESCRIPTION

xil_export () moves an image from XIL processing space into application space. This function returns XIL_SUCCESS if the export succeeds, and XIL_FAILURE if the export fails.

By calling xil_export () to move an image from XIL processing space into application space, the application gains access to information about how image data is stored in memory. The exported image’s data must be accessed by calling xil_get_memory_storage(3). xil_export () can also be used to ensure that the image’s data storage remains in main memory. This prevents the image from being moved to another device. Exporting an image may cause a reduction in the performance of operations.

xil_import () moves an image from application space into XIL processing space. An image exported for read-only purposes may be re-imported in the most efficient way if the parameter change_flag is set to FALSE (in other words, if the image was not modified). You must set the change flag to TRUE when you import an image if you make any modifications to it while it is exported.

When an application calls xil_import (), the XIL library is free to move the image’s data to another address space and to another format; therefore, importing an image invalidates the information returned by a previous xil_get_memory_storage(3). If the image is exported again, the image data is unlikely to appear in the same memory location as the last time it was exported, and it’s unlikely to have the same format as the last time. Therefore, xil_get_memory_storage(3) must be called after each xil_export () in order to obtain the current memory location and format for the image data.

To ensure that image data is not moved and is not reformatted, an application could export the image but never import it again. However, this prevents the XIL library from moving the image to an accelerator, if one exists, and it prevents the library from implementing its deferred execution scheme; thus, application performance is significantly degraded. After manipulating an exported image’s data, it’s usually best for an application to take advantage of available acceleration by importing the image; then, when it needs to manipulate data again, it can export the image and get new pointers to the data and new format information by calling xil_get_memory_storage(3).

xil_get_exported () returns the export status of an image. One of three possible values is returned:

0 if the image is not exported

1 if the image is exported

-1 if the image is not exportable

ERRORS

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

NOTES

Images created from a window with xil_create_from_window(3) or from a device with xil_create_from_device(3) cannot be exported. A description of the storage of the image cannot be requested if the image is not exported.

Museum