IM: Image Storage

IM - An Imaging Tool

previous page next page

Image Storage

Detailed Description

See im.h

Modules

 File Format SDK
 imImage Storage
 File Formats

Data Structures

class  imImageFile
 C++ Wrapper for the Image File Structure. More...

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)
const void * imFileGetAttribute (imFile *ifile, const char *attrib, int *data_type, int *count)
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)

Enumeration Type Documentation

enum imErrorCodes
 

File Access Error Codes

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  Insuficient memory
IM_ERR_COUNTER  Interrupted by the counter 
00059 {
00060   IM_ERR_NONE,     /**< No error. */
00061   IM_ERR_OPEN,     /**< Error while opening the file (read or write). */
00062   IM_ERR_ACCESS,   /**< Error while accessing the file (read or write). */
00063   IM_ERR_FORMAT,   /**< Invalid or unrecognized file format. */
00064   IM_ERR_DATA,     /**< Invalid or unsupported data. */
00065   IM_ERR_COMPRESS, /**< Invalid or unsupported compression. */
00066   IM_ERR_MEM,      /**< Insuficient memory */
00067   IM_ERR_COUNTER   /**< Interrupted by the counter */
00068 };

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.

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

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. 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 writting.
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. 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.

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.

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 pallete if any.
"palette" must be a 256 colors alocated 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-botttom 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: bool, 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]


previous page start next page