Expand/Shrink

IupImage

Definition: include pGUI.e

Ihandle ih = IupImage(integer width, height, object pixels)
Description: Creates an image to be shown on a label, button, toggle, or as a cursor.

IupImageRGB and IupImageRGBA are similar except for the content of pixels.
IupImage is limited to 256 colour (8 bit) bitmaps, whereas IupImageRGB and IupImageRGBA are used to create 24 and 32 bit bitmaps respectively.

width: Image width in pixels.
height: Image height in pixels.
pixels: Usually a (flat) sequence containing the value of each pixel, can also be an atom pointer to already-initialised memory.
IupImage uses 1 value per pixel, IupImageRGB uses 3 values and IupImageRGBA uses 4 values per pixel.
Each value is always 8 bit (as per/see poke) ie 0..255, hence the mapping of IupImage/RGB/A -> 8/24/32 bit bitmaps.
Origin is at the top-left corner and data is oriented top to bottom, and left to right.
The pixels array is duplicated internally so you can discard it after the call.

Returns: the identifier of the created element.
pwa/p2js: Supported, note however that IupImage() creates the image data immediately and is limited to the default 16 colours listed below (reproduced as constant $IupImageDefaultColours within p2js.js/IupImage(), fyi and should that help any). Therefore, you cannot set the colour indices ("0","1",etc) after calling IupImage(), and you haven’t got a handle with which to try that before, and hence must resort to using IupImageRGB[A]() when those 16 colours do not suffice (and which you would need for any image with more than 256 colours anyway). Also note there is a potentially significant performance issue when using binary strings to construct the pixel data, as explained in repeat(), that can be allieviated by setting the (new in 1.0.2, not necessary for repeat 0) allow_strings parameter of that function to false.
See Also: IupLoadImage, IupImageLibOpen, imFileImageLoadBitmap, IupLabel, IupButton, IupToggle, IupDestroy
Notes: Application icons are usually 32x32. Toolbar bitmaps are 24x24 or smaller. Menu bitmaps and small icons are 16x16 or smaller.

Images created with the IupImage* constructors can be reused in different elements.

The images should be destroyed when they are no longer necessary, by means of the IupDestroy function.
To destroy an image, it cannot be in use, i.e the controls where it is used should be destroyed first.
Images that were associated with controls by names are automatically destroyed in IupClose.

Please observe the rules for creating cursor images: CURSOR.

Some examples can be found in demo\pGUI\sample.exw
Usage: Images are used in elements such as buttons and labels by attributes that points to names registered with IupSetHandle.
You can also use IupSetAttributeHandle to shortcut the setting of an image as an attribute. For example: 

Ihandle image = IupImage(width, height, pixels);

IupSetHandle("MY_IMAGE_NAME", image);
IupSetAttribute(label, "IMAGE", "MY_IMAGE_NAME");
or
IupSetAttributeHandle(label, "IMAGE", image); -- an automatic name will be created internally

In Windows, names of resources in RC files linked with the application are also accepted.
In GTK, names of GTK Stock Items are also accepted.
In Motif, names of bitmaps installed on the system are also accepted. For example: 

IupSetAttribute(label, "IMAGE", "TECGRAF_BITMAP");  // available in the "etc/iup.rc" file
or
IupSetAttribute(label, "IMAGE", "gtk-open");  // available in the GTK Stock Items

In all drivers, a path to a file name can also be used as the attribute value (since 3.0).
But the available file formats supported are system dependent.
The Windows driver supports BMP, ICO and CUR.
The GTK driver supports the formats supported by the GDK-PixBuf library, such as BMP, GIF, JPEG, PCX, PNG, TIFF and many others.
The Motif driver supports the X-Windows bitmap. For example: 

IupSetAttribute(label, "IMAGE", "../etc/tecgraf.bmp");

A more format independent approach can be reached using the IUP-IM Functions.
Colors: In Motif, the alpha channel in RGBA images is always composed with the control BGCOLOR by IUP prior to setting the image at the control.
In Windows and in GTK, the alpha channel is composed internally by the system.
But in Windows for some controls the alpha must be composed a priori also, it includes: IupMenuItem and IupSubmenu always; and IupToggle when NOT using Visual Styles.
This implies that if the control background is not uniform then probably there will be a visible difference where it should be transparent.

For IupImage, if a color is not set, then it is used a default color for the 16 first colors. The default color table is the same for Windows, GTK and Motif: 

 0 =   0,  0,  0 (black)
 1 = 128,  0,  0 (dark red)
 2 =   0,128,  0 (dark green) 
 3 = 128,128,  0 (dark yellow)
 4 =   0,  0,128 (dark blue)
 5 = 128,  0,128 (dark magenta) 
 6 =   0,128,128 (dark cian) 
 7 = 192,192,192 (gray)
 8 = 128,128,128 (dark gray)
 9 = 255,  0,  0 (red)     
10 =   0,255,  0 (green)
11 = 255,255,  0 (yellow)
12 =   0,  0,255 (blue)
13 = 255,  0,255 (magenta)
14 =   0,255,255 (cian)  
15 = 255,255,255 (white)

For images with more than 16 colors, and up to 256 colors, all the color indices must be defined up to the maximum number of colors. For example, if the biggest image index is 100, then all the colors from i=16 up to i=100 must be defined even if some indices are not used.
Samples: You can obtain several images from the IupImageLib, a library of pre-defined images.
To view the images you can use the IupView in the applications included in the distribution, available at the Download.
IupView is also capable of converting several image formats into an IupImage, and save IUP images as LED, Lua or ICO.

The EdPatt and the IMLAB applications can load and save images in simplified LED format.
They allow operations such as importing GIF images and exporting them as IUP images.
EdPatt allows you to manually edit the images, and also have support for images in IupLua.
Attributes:
"0","1",etcx Color in index 0,1,etc. The indices can range from 0 to 255. The total number of colors is limited to 256 colors. Be careful when setting colors, since they are attributes they follow the same storage rules for standard attributes.

The values are integer numbers from 0 to 255, one for each color in the RGB triple (For ex: "64 190 255"). If the value of a given index is "BGCOLOR", the color used will be the background color of the element on which the image will be inserted. The "BGCOLOR" value must be defined within an index less than 16.

Used only for images created with IupImage. As noted above, not supported under pwa/p2js.
AUTOSCALE automatically scale the image by a given real factor. If not defined the global attribute IMAGEAUTOSCALE will be used. Values are the same of the global attribute. (since 3.16)
BGCOLOR The color used for transparency. If not defined uses the BGCOLOR of the control that contains the image.
BPP (read-only) returns the number of bits per pixel in the image. Images created with IupImage returns 8, with IupImageRGB returns 24 and with IupImageRGBA returns 32. (since 3.0)
CLEARCACHE (write-only): clears the internal native image cache, so WID can be dynamically changed. (since 3.24)
CHANNELS (read-only) returns the number of channels in the image. Images created with IupImage returns 1, with IupImageRGB returns 3 and with IupImageRGBA returns 4. (since 3.0)
DPI resolution expected for display. Used when AUTOSCALE=DPI. If not defined the global attribute IMAGESDPI will be used. (since 3.23)
HEIGHT (read-only) Image height in pixels.
HOTSPOT Hotspot is the position inside a cursor image indicating the mouse-click spot.
Its value is given by the x and y coordinates inside a cursor image.
Its value has the format "x:y", where x and y are integers defining the coordinates in pixels. Default: "0:0".
RASTERSIZE (read-only) returns the image size in pixels. (since 3.0)
RESHAPE (write-only): given a new size if format "widthxheight", allocates enough memory for the new size and changes WIDTH and HEIGHT attributes.
The image contents are ignored and it will contain trash after the reshape. (since 3.24)
RESIZE (write-only): given a new size if format "widthxheight", changes WIDTH and HEIGHT attributes, and resizes the image contents using bilinear interpolation for RGB and RGBA images and nearest neighborhood for 8 bits. (since 3.24)
PL: Does nothing on a previoously displayed image unless CLEARCACHE is first set. I then found I had to recreate the image from the original pixel array, otherwise repeated bilinear interpolation rather rapidly degrades it, in my case to all black, and consequently setting CLEARCACHE on the brand new image was no longer necessary or helpful.
SCALED (read-only): returns Yes if the image has been resized. (since 3.25)
ORIGINALSCALE (read-only): returns the width and height before the image was scaled. (since 3.25)
WID (read-only) returns the internal pixels data pointer. (since 3.0)
WIDTH (read-only) Image width in pixels.