ImageImportPlugin::ImportImageFile

Defined in: C4Plugins.h

Imports an image from a file.

Prototype

EngineResult ImportImageFile(const char *name, void **image, Integer2D *size, uint32 *flags = nullptr, int32 index = 0) = 0;

Parameters

`name`	The file name of the image, relative to the engine executable.
`image`	A pointer to a location that receives a pointer to the buffer in which the image is stored.
`size`	A pointer to a location that receives the dimensions of the image. This cannot be `nullptr`.
`flags`	A pointer to a location that receives flags pertaining to the image. This can be `nullptr` if this information is not needed.
`index`	The zero-based index of the image to import.

Description

The ImportImageFile function imports an image from the file specified by the name paramater. If the function succeeds, then the return value is kEngineOkay. If an error occurred, then the result code corresponding to the error is returned. A pointer to a buffer containing the image data is stored in the location specified by the image parameter. This buffer is allocated by the implementation of the ImportImageFile function. Once the image data is no longer needed, this buffer should be released by calling the ImageImportPlugin::ReleaseImageData function. The horizontal and vertical dimensions of the image are stored in the location specified by the size parameter. If the flags parameter is not nullptr, then flags pertaining to the image are stored in the location it points to. The flags can be a combination (through logical OR) of the following constants.

kImageImportAlpha The imported image includes an alpha channel.

The index parameter specifies which image to import for files containing more than one image. It should be in the range [0, n − 1], where n is the image count returned by the ImageImportPlugin::GetImageFileInfo function. The ImportImageFile function must be overridden by subclasses of the ImageImportPlugin class.