Collaboration diagram for Image Storage:

Modules
	File Format SDK
	imImage Storage
	File Formats
Typedefs
typedef struct _imFile	imFile
Enumerations
enum	imErrorCodes { IM_ERR_NONE, IM_ERR_OPEN, IM_ERR_ACCESS, IM_ERR_FORMAT, IM_ERR_DATA, IM_ERR_COMPRESS, IM_ERR_MEM, IM_ERR_COUNTER }
Functions
imFile *	imFileOpen (const char file_name, int error)
imFile *	imFileOpenAs (const char file_name, const char format, int *error)
imFile *	imFileNew (const char file_name, const char format, int *error)
void	imFileClose (imFile *ifile)
void *	imFileHandle (imFile *ifile, int index)
void	imFileGetInfo (imFile ifile, char format, char compression, int image_count)
void	imFileSetInfo (imFile ifile, const char compression)
void	imFileSetAttribute (imFile ifile, const char attrib, int data_type, int count, const void *data)
void	imFileSetAttribInteger (const imFile ifile, const char attrib, int data_type, int value)
void	imFileSetAttribReal (const imFile ifile, const char attrib, int data_type, double value)
void	imFileSetAttribString (const imFile ifile, const char attrib, const char *value)
const void *	imFileGetAttribute (imFile ifile, const char attrib, int data_type, int count)
int	imFileGetAttribInteger (const imFile ifile, const char attrib, int index)
double	imFileGetAttribReal (const imFile ifile, const char attrib, int index)
const char *	imFileGetAttribString (const imFile ifile, const char attrib)
void	imFileGetAttributeList (imFile ifile, char attrib, int attrib_count)
void	imFileGetPalette (imFile ifile, long palette, int *palette_count)
void	imFileSetPalette (imFile ifile, long palette, int palette_count)
int	imFileReadImageInfo (imFile ifile, int index, int width, int height, int file_color_mode, int *file_data_type)
int	imFileWriteImageInfo (imFile *ifile, int width, int height, int user_color_mode, int user_data_type)
int	imFileReadImageData (imFile ifile, void data, int convert2bitmap, int color_mode_flags)
int	imFileWriteImageData (imFile ifile, void data)

Detailed Description

: See im.h

Enumeration Type Documentation

enum imErrorCodes

File Access Error Codes

: In Lua use im.ErrorStr(err) to convert the error number into a string.

Enumerator:

IM_ERR_NONE	No error.
IM_ERR_OPEN	Error while opening the file (read or write).
IM_ERR_ACCESS	Error while accessing the file (read or write).
IM_ERR_FORMAT	Invalid or unrecognized file format.
IM_ERR_DATA	Invalid or unsupported data.
IM_ERR_COMPRESS	Invalid or unsupported compression.
IM_ERR_MEM	Insufficient memory
IM_ERR_COUNTER	Interrupted by the counter

Function Documentation

imFile* imFileOpen	(	const char *	file_name,
		int *	error
	)

Opens the file for reading. It must exists. Also reads file header. It will try to identify the file format. See also imErrorCodes.
In Lua the IM file metatable name is "imFile". When converted to a string will return "imFile(%p)" where p is replaced by the userdata address. If the file is already closed by im.FileClose, then it will return also the suffix "-closed".

im.FileOpen(file_name: string) -> ifile: imFile, error: number [in Lua 5]

imFile* imFileOpenAs	(	const char *	file_name,
		const char *	format,
		int *	error
	)

Opens the file for reading using a specific format. It must exists. Also reads file header. See also imErrorCodes and File Formats.

im.FileOpenAs(file_name, format: string) -> ifile: imFile, error: number [in Lua 5]

imFile* imFileNew	(	const char *	file_name,
		const char *	format,
		int *	error
	)

Creates a new file for writing using a specific format. If the file exists will be replaced.
It will only initialize the format driver and create the file, no data is actually written. See also imErrorCodes and File Formats.

im.FileNew(file_name: string, format: string) -> ifile: imFile, error: number [in Lua 5]

void imFileClose ( imFile * ifile )

Closes the file.
In Lua if this function is not called, the file is closed by the garbage collector.

im.FileClose(ifile: imFile) [in Lua 5]

ifile:Close() [in Lua 5]

void* imFileHandle	(	imFile *	ifile,
		int	index
	)

Returns an internal handle. index=0 returns always an imBinFile* handle, but for some formats returns NULL because they do not use imBinFile (like AVI and WMV). index=1 return an internal structure used by the format, usually is a handle to a third party library structure. This is file format dependent.

ifile:Handle() -> handle: userdata [in Lua 5]

void imFileGetInfo	(	imFile *	ifile,
		char *	format,
		char *	compression,
		int *	image_count
	)

Returns file information. image_count is the number of images in a stack or the number of frames in a video/animation or the depth of a volume data.
compression and image_count can be NULL.
These information are also available as attributes:

FileFormat (string)

FileCompression (string)

FileImageCount IM_INT (1)

See also File Formats.

ifile:GetInfo() -> format: string, compression: string, image_count: number [in Lua 5]

void imFileSetInfo	(	imFile *	ifile,
		const char *	compression
	)

Changes the write compression method.
If the compression is not supported will return an error code when writing.
Use NULL to set the default compression. You can use the imFileGetInfo to retrieve the actual compression but only after imFileWriteImageInfo. Only a few formats allow you to change the compression between frames.

ifile:SetInfo(compression: string) [in Lua 5]

void imFileSetAttribute	(	imFile *	ifile,
		const char *	attrib,
		int	data_type,
		int	count,
		const void *	data
	)

Changes an extended attribute.
The data will be internally duplicated.
If data is NULL the attribute is removed. If data_type is BYTE then count can be -1 to indicate a NULL terminated string. See also imDataType.

ifile:SetAttribute(attrib: string, data_type: number, data: table of numbers or string) [in Lua 5]

If data_type is IM_BYTE, as_string can be used as data.

void imFileSetAttribInteger	(	const imFile *	ifile,
		const char *	attrib,
		int	data_type,
		int	value
	)

Changes an extended attribute as an integer.

void imFileSetAttribReal	(	const imFile *	ifile,
		const char *	attrib,
		int	data_type,
		double	value
	)

Changes an extended attribute as a real.

void imFileSetAttribString	(	const imFile *	ifile,
		const char *	attrib,
		const char *	value
	)

Changes an extended attribute as a string.

const void* imFileGetAttribute	(	imFile *	ifile,
		const char *	attrib,
		int *	data_type,
		int *	count
	)

Returns an extended attribute.
Returns NULL if not found. data_type and count can be NULL. See also imDataType.

ifile:GetAttribute(attrib: string, [as_string: boolean]) -> data: table of numbers or string, data_type: number [in Lua 5]

If data_type is IM_BYTE, as_string can be used to return a string instead of a table.

ifile:GetAttributeRaw(attrib: string) -> data: userdata, data_type, count: number [in Lua 5]

int imFileGetAttribInteger	(	const imFile *	ifile,
		const char *	attrib,
		int	index
	)

Returns an extended attribute as an integer.

double imFileGetAttribReal	(	const imFile *	ifile,
		const char *	attrib,
		int	index
	)

Returns an extended attribute as a real.

const char* imFileGetAttribString	(	const imFile *	ifile,
		const char *	attrib
	)

Returns an extended attribute as a string.

void imFileGetAttributeList	(	imFile *	ifile,
		char **	attrib,
		int *	attrib_count
	)

Returns a list of the attribute names.
"attrib" must contain room enough for "attrib_count" names. Use "attrib=NULL" to return only the count.

ifile:GetAttributeList() -> data: table of strings [in Lua 5]

void imFileGetPalette	(	imFile *	ifile,
		long *	palette,
		int *	palette_count
	)

Returns the palette if any.
"palette" must be a 256 colors allocated array.
Returns zero in "palette_count" if there is no palette. "palette_count" is >0 and <=256.

ifile:GetPalette() -> palette: imPalette [in Lua 5]

void imFileSetPalette	(	imFile *	ifile,
		long *	palette,
		int	palette_count
	)

Changes the pallete.
"palette_count" is >0 and <=256.

ifile:SetPalette(palette: imPalette) [in Lua 5]

int imFileReadImageInfo	(	imFile *	ifile,
		int	index,
		int *	width,
		int *	height,
		int *	file_color_mode,
		int *	file_data_type
	)

Reads the image header if any and returns image information.
Reads also the extended image attributes, so other image attributes will be available only after calling this function.
Returns an error code. index specifies the image number between 0 and image_count-1.
Some drivers reads only in sequence, so "index" can be ignored by the format driver.
Any parameters can be NULL. This function must be called at least once, check each format documentation. See also imErrorCodes, imDataType, imColorSpace and imColorModeConfig.

ifile:ReadImageInfo([index: number]) -> error: number, width: number, height: number, file_color_mode: number, file_data_type: number [in Lua 5]

Default index is 0.

int imFileWriteImageInfo	(	imFile *	ifile,
		int	width,
		int	height,
		int	user_color_mode,
		int	user_data_type
	)

Writes the image header. Writes the file header at the first time it is called. Writes also the extended image attributes.
Must call imFileSetPalette and set other attributes before calling this function.
In some formats the color space will be converted to match file format specification.
Returns an error code. This function must be called at least once, check each format documentation. See also imErrorCodes, imDataType, imColorSpace and imColorModeConfig.

ifile:WriteImageInfo(width: number, height: number, user_color_mode: number, user_data_type: number) -> error: number [in Lua 5]

int imFileReadImageData	(	imFile *	ifile,
		void *	data,
		int	convert2bitmap,
		int	color_mode_flags
	)

Reads the image data with or without conversion.
The data can be converted to bitmap when reading. Data type conversion to byte will always scan for min-max then scale to 0-255, except integer values that min-max are already between 0-255. Complex to real conversions will use the magnitude.
Color mode flags contains packed, alpha and top-bottom information. If flag is 0 means unpacked, no alpha and bottom up. If flag is -1 the file original flags are used.
Returns an error code. See also imErrorCodes, imDataType, imColorSpace and imColorModeConfig.

ifile:ReadImageData(data: userdata, convert2bitmap: boolean, color_mode_flags: number) -> error: number [in Lua 5]

int imFileWriteImageData	(	imFile *	ifile,
		void *	data
	)

Writes the image data.
Returns an error code.

ifile:WriteImageData(data: userdata) -> error: number [in Lua 5]

Image Storage

Modules

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation