Functions to Create/Destroy Image Objects

Create or destroy an internal image object in the Intel® Graphics Technology runtime. This topic only applies to Intel® 64 and IA-32 architectures targeting Intel® Graphics Technology.

Syntax

C++ Interface: Templates and Constructors

template <class T>  class GfxImage2D:
     GfxImage2D(T * ptr, size_t height, size_t width, int format = 0)

template <class T>  class GfxSharedImage2D:
     GfxSharedImage2D(T * ptr, size_t height, size_t width, int format = 0)

C Interface: Constructor Equivalent

GfxResourceHandle _GFX_create_image_2d (void * ptr, size_t element_size, size_t height, size_t width, int format, int flags);

C Interface: Destructor Equivalent

int _GFX_close_resource_handle(GfxResourceHandle handle);

Parameters

ptr

The pointer to the host data that is to be either shared as, or copied to, 2D tiled memory.

element_size

The size of each element, in bytes. This argument is provided for the C version only, the C++ version uses templates to indicate the size of the element.

height

The height of the image, in rows.

width

The width of the image, in elements

format

The pixel format for the image.

When format= 0, the runtime selects the most appropriate format for complete bitwise representation of the data element of the given size.

Other acceptable values are specific to the underlying system video layer (DirectX 11 on Windows 8, DirectX 9 on Windows 7)

flags

A bit mask that indicates various additional properties of the image object. Supported values are:

GFX_MEMORY_GPU_ONLY	Indicates that the image is created in target memory, and the host data is copied to the target copy upon image creation, and is copied back upon image destruction.
GFX_MEMORY_SHARED	Indicates that the image is shared between the host and the target, and requires no copying.

handle

A handle to the internal image object returned by _GFX_create_image_2d.

Description

Either the constructors of the C++ classes or the _GFX_create_image_2d C-style function create an internal image object in the Intel® Graphics Technology runtime.

The internal image object is kept alive at least until one of the following happens:

The destructor of GfxImage2D / GfxSharedImage2D (C++ version) or _GFX_close_resource_handle (C version) is called.
There is no active kernel that uses, or might use, this image.

This makes it possible to write compact and intuitive user code, where the burden of safe image lifetime management is put onto the runtime.

GfxSharedImage2D shares the 2D image between the host and the target. GfxImage2D keeps the 2D image on the target only.

While the shared 2D image does not require read or write operations to synchronize the host and target memory, it does not provide the tiled memory access optimization on the target side. In contrast, the target 2D image enables efficient 2D memory access on the target side but requires data to be copied to or from the target memory before and after the offload task execution. The shared image, GfxSharedImage2D, requires the host side memory to be page-aligned, that is aligned to 4096 bytes. If the memory is not properly aligned, the target image is created instead: GfxSharedImage2D behaves as GfxImage2D.

Return Values

Note

These return values apply only to the C versions.

For _GFX_create_image_2d

NULL	An error has occurred.
A non-NULL handle to the internal image object	The function succeeded.

Note

GfxImage2D or GfxSharedImage2D objects for C++ version are inherited from GfxImage2DBase whose only member is GfxResourceHandle and which is essentially a C++ style holder of the handle.

For _GFX_close_resource_handle

`GFX_SUCCESS (0)`	The function succeeded.
A non-zero error code	An error has occurred. Use the function _GFX_get_last_error() to get the specific error code. Additonally, gfx_rt.h defines various error status values.