Modules | Typedefs | Enumerations | Functions

Image Storage

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

imFileimFileOpen (const char *file_name, int *error)
imFileimFileOpenAs (const char *file_name, const char *format, int *error)
imFileimFileNew (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

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]