## IUP-IM Functions

Functions to load/save an IupImage from/to a file using the IM library. The function can load or save the formats: BMP, JPEG, GIF, TIFF, PNG, PNM, PCX, ICO and others. For more information about the IM library see http://www.tecgraf.puc-rio.br/im.

### Initialization and Usage

To generate an application that uses this function, the program must be linked with the IM library and with the function library (im and iupim libraries). The "iupim.h" file must also be included in the source code.

To make the functions available in Lua use require"iupluaim" or manually call the initialization function in C, iupimlua_open, after calling iuplua_open. When manually calling the function the iupluaim.h file must also be included in the source code and the program must be linked to the iupluaim library.

### Load

    Ihandle* IupLoadImage(const char* file_name); [in C]
    iup.LoadImage(file_name: string) -> (elem: ihandle) [in Lua]

file_name: Name of the file to be loaded.

Returns: the identifier of the created image, or NULL if an error occurs. When failed the global attribute "IUPIM_LASTERROR" is set with a message describing the error.

### Save

    int IupSaveImage(Ihandle* ih, const char* file_name, const char* format); [in C]
    iup.SaveImage(ih: ihandle, file_name, format: string) -> (ret: boolean) [in Lua]

ih: handle of the IupImage.
file_name: Name of the file to be loaded.
format: format descriptor for IM. For ex: "BMP", "JPEG", "GIF", "TIFF", "PNG", "PNM", "PCX", "ICO", etc.

Returns: zero if failed. When failed the global attribute "IUPIM_LASTERROR" is set with a message describing the error.

### LoadAnimation (since 3.17)

    Ihandle* IupLoadAnimation(const char* file_name); [in C]
    iup.LoadAnimation(file_name: string) -> (elem: ihandle) [in Lua]

file_name: Name of the file to be loaded.

Returns: the identifier of the created animation, or NULL if an error occurs. When failed the global attribute "IUPIM_LASTERROR" is set with a message describing the error.

An animation is simply an IupUser element with several IupImage elements as children. The total number of images can be obtained using IupGetChildCount. The time between frames is defined by the FRAMETIME attribute if FPS is present on the file.

IM supports loading of multiple images from the same file for the following formats: GIF, TIFF, AVI (additional library) and WMV (additional library).

### LoadAnimationFrames (since 3.17)

    Ihandle* IupLoadAnimationFrames(const char** file_name_list, int file_count); [in C]
    iup.LoadAnimationFrames(file_name_list: table of strings, file_count: number) -> (elem: ihandle) [in Lua]

file_name_list: List of file names to be loaded.
file_count: number of file names in the list.

Returns: the identifier of the created animation, or NULL if an error occurs. When failed the global attribute "IUPIM_LASTERROR" is set with a message describing the error. The FRAMETIME attribute is not set.

### Native Handle to imImage

    imImage* IupGetNativeHandleImage(void* handle); [in C]
    iup.GetNativeHandleImage(handle: userdata) -> (image: imImage) [in Lua]

handle: image native handle. In Win32 is a HANDLE of a DIB. In GTK is a GdkPixbuf*. In Motif is a Pixmap. Its memory is released after the imImage is created. In Lua is a light user data.

Returns: the imImage* handle. Useful when pasting data from a IupClipboard.

You must include the "im_image.h" header before the "iupim.h" to enable these functions.

### imImage to Native Handle

    imImage* IupGetImageNativeHandle(imImage* image); [in C]
    iup.GetImageNativeHandle(image: imImage) -> (handle: userdata) [in Lua]

image: the imImage* handle. Must be a bitmap image.

Returns: the image native handle. In Win32 is a HANDLE for a DIB. In GTK is a GdkPixbuf*. In Motif is a Pixmap. Usefull when copying data to a IupClipboard. In Lua is a light user data.

You must include the "im_image.h" header before the "iupim.h" to enable these functions.

### imImage to IupImage (since 3.10)

    Ihandle* IupImageFromImImage(imImage* image); [in C]
    iup.ImageFromImImage(image: imImage) -> (elem: ihandle) [in Lua]

image: the imImage* handle. Must be a bitmap image.

Returns: the IupImage handle.

You must include the "im_image.h" header before the "iupim.h" to enable these functions.

### IupImage to imImage (since 3.22)

    imImage* IupImageToImImage(Ihandle* elem); [in C]
    iup.ImageToImImage(elem: ihandle) -> (image: imImage) [in Lua]

elem: handle of the IupImage. Must be manually created with the IupImage* constructors, can NOT be an image loaded from system resources or from native stock images.

Returns: the imImage* handle.

You must include the "im_image.h" header before the "iupim.h" to enable these functions.

### See Also

IupImage, IupSaveImageAsText, IupClipboard