IupImage, IupImageRGB, IupImageRGBA
Creates an image to be shown on a label, button, toggle, or as a cursor.
(IupImageRGB and IupImageRGBA since IUP 3.0)
Creation
Ihandle* IupImage(int width, int height, const unsigned char *pixels); [in C]
Ihandle* IupImageRGB(int width, int height, const unsigned char *pixels); [in C]
Ihandle* IupImageRGBA(int width, int height, const unsigned char *pixels); [in C]
iup.image{line0: table, line1: table, ...; colors = colors: table} -> (elem: ihandle) [in Lua]
iup.imagergb {width = width: number, height = height: number, pixels = pixels: table} -> (elem: ihandle) [in Lua]
iup.imagergba{width = width: number, height = height: number, pixels = pixels: table} -> (elem: ihandle) [in Lua]
image(width, height, pixel0, pixel1, ...) [in LED]
imagergb(width, height, pixel0, pixel1, ...) [in LED]
imagergba(width, height, pixel0, pixel1, ...) [in LED]
width:
Image width in pixels.
height:
Image height in pixels.
pixels:
Vector containing the value of each pixel. IupImage uses 1 value per
pixel, IupImageRGB uses 2 values and IupImageRGBA uses 3
values per pixel. Each value is always 8 bit. 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 discart it after
the call.
pixel0, pixel1, ...:
Value of the pixels. But for IupImageRGB and IupImageRGBA in
fact will be one value for each color channel.
line0, line1: unnamed tables, one for each line containing
pixels values. See Notes bellow.
colors: table named colors containg the colors indices. See Notes
bellow.
Returns: the identifier of the created element, or NULL if an error occurs.
Attributes
"0"
Color in index 0.
"1"
Color in index 1.
...
"i"
Color in index i.
The indices can range from 0 to 255. The total number of colors is limited to 256 colors. Notice that in Lua the first index in the array is "1", the index "0" is ignored in IupLua. 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.
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)
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)
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)
WID (read-only): returns the pixels data pointer. (since 3.0)
WIDTH (read-only): Image width in pixels.
Notes
Application icons are usually 32x32. Toolbar bitmaps are 24x24 or smaller. Menu bitmaps and small icons are 16x16 or smaller.
An image created with all IupImage* can be reused for different buttons and labels.
The images must be destroyed when they are no longer necessary, by means of the IupDestroy function. To destroy an image, it cannot be in use. Please observe the rules for creating cursor images: CURSOR.
Colors
In Windows and Motif, the alpha channel in RGBA images is composed with the BGCOLOR when the image is used in a control. The images are mapped to 24bpp. In GTK the alpha channel is composited internally by GDK.
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. Note that to use more than 128 colors you must use an "unsigned char*" pointer and simply cast it to "char*" when calling the IupImage function.
Samples
You can donwload several IUP images in LED format from iup_images.zip. To view the images you can use the LED viewer application, see 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. Some of these images are already available in the pre-defined image library.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.
IupLua
In Lua, the 8bpp image can also be created using an unnamed table, using a series of tables for each line. Width and height will be guessed from the tables sizes. For example:
img = iup.image{
{ 1,2,3,3,3,3,3,3,3,2,1 },
{ 2,1,2,3,3,3,3,3,2,1,2 },
{ 3,2,1,2,3,3,3,2,1,2,3 },
{ 3,3,2,1,2,3,2,1,2,3,3 },
{ 3,3,3,2,1,2,1,2,3,3,3 },
{ 3,3,3,3,2,1,2,3,3,3,3 },
{ 3,3,3,2,1,2,1,2,3,3,3 },
{ 3,3,2,1,2,3,2,1,2,3,3 },
{ 3,2,1,2,3,3,3,2,1,2,3 },
{ 2,1,2,3,3,3,3,3,2,1,2 },
{ 1,2,3,3,3,3,3,3,3,2,1 };
colors = {
"0 1 0",
"255 0 0",
"255 255 0"
}
}
But after the image is created in Lua, the line tables are not accessible anymore, since "img[1]" will return the attribute "1" value which is the color "0 1 0". To acess the original table values you must use "raawget", for example:
lin1 = rawget(img, 1)
will return the first line of the original table. But if the image was created in C then there is no way to access its values.
For RGB and RGBA images the creation is different, and must contains explicit values for width and height. For example:
img = iup.imagergb{
width = 11,
height = 11,
pixels = {
0,255,0, 255, 0,0, 255,255,0, 255,255,0, 255,255,0, 255,255,0, 255,255,0, 255,255,0, 255,255,0, 255, 0,0, 0,255,0,
255, 0,0, 0,255,0, 255, 0,0, 255,255,0, 255,255,0, 255,255,0, 255,255,0, 255,255,0, 255, 0,0, 0,255,0, 255, 0,0,
255,255,0, 255, 0,0, 0,255,0, 255, 0,0, 255,255,0, 255,255,0, 255,255,0, 255, 0,0, 0,255,0, 255, 0,0, 255,255,0,
255,255,0, 255,255,0, 255, 0,0, 0,255,0, 255, 0,0, 255,255,0, 255, 0,0, 0,255,0, 255, 0,0, 255,255,0, 255,255,0,
255,255,0, 255,255,0, 255,255,0, 255, 0,0, 0,255,0, 255, 0,0, 0,255,0, 255, 0,0, 255,255,0, 255,255,0, 255,255,0,
255,255,0, 255,255,0, 255,255,0, 255,255,0, 255, 0,0, 0,255,0, 255, 0,0, 255,255,0, 255,255,0, 255,255,0, 255,255,0,
255,255,0, 255,255,0, 255,255,0, 255, 0,0, 0,255,0, 255, 0,0, 0,255,0, 255, 0,0, 255,255,0, 255,255,0, 255,255,0,
255,255,0, 255,255,0, 255, 0,0, 0,255,0, 255, 0,0, 255,255,0, 255, 0,0, 0,255,0, 255, 0,0, 255,255,0, 255,255,0,
255,255,0, 255, 0,0, 0,255,0, 255, 0,0, 255,255,0, 255,255,0, 255,255,0, 255, 0,0, 0,255,0, 255, 0,0, 255,255,0,
255, 0,0, 0,255,0, 255, 0,0, 255,255,0, 255,255,0, 255,255,0, 255,255,0, 255,255,0, 255, 0,0, 0,255,0, 255, 0,0,
0,255,0, 255, 0,0, 255,255,0, 255,255,0, 255,255,0, 255,255,0, 255,255,0, 255,255,0, 255,255,0, 255, 0,0, 0,255,0}
}
This produces visually the same result as the previous example using "iup.image".