# Aros/Developer/Docs/Libraries/Icon

* Navbar for the Aros wikibook
* Aros User
* Aros User Docs
* Aros User FAQs
* Aros User Applications
* Aros User DOS Shell
* Aros/User/AmigaLegacy
* Aros Dev Docs
* Aros Developer Docs
* Porting Software from AmigaOS/SDL
* For Zune Beginners
* Zune .MUI Classes
* For SDL Beginners
* Aros Developer BuildSystem
* Specific platforms
* Aros x86 Complete System HCL
* Aros x86 Audio/Video Support
* Aros x86 Network Support
* Aros Intel AMD x86 Installing
* Aros Storage Support IDE SATA etc
* Aros Poseidon USB Support
* x86-64 Support
* Motorola 68k Amiga Support
* Linux and FreeBSD Support
* Windows Mingw and MacOSX Support
* Android Support
* Arm Raspberry Pi Support
* PPC Power Architecture
* misc
* Aros Public License

## Introduction

* OLD - OS1.x (4 col) - OS 2/3 (4 col)
* NEW - NewIcons (size 36x40 x 32 col) - GlowIcons (size 46x46 x 256 col) - PowerIcons (24bit)
Possibilities for the future
* SVG or SVGZ - Haiku HVIF has a reduced format.
There are several formats used by Amiga/AROS computers to display icons for each program/project you want to access from the graphical user interface Workbench.
The Classic Icon is the basis for three of the Icon styles supported by AROS. The Amiga Glow Icon is a Classic Icon (Old Icon Format) with OS 3.5 IFF Icon Data attached at the end. The IFF data contains the images that AROS displays. An OS4 icon is a Classic Icon with OS 3.5 Data attached. But unlike a Glow Icon it only has a 'FACE' chunk with no 'IMAG' chunks. It has 2 'ARGB' chunks at the end of the Icon file that are used to display. The AROS Hybrid Icon or ARGB Icon is similar to the OS4 Icon but it has a complete Glow Icon that 2 ARGB chunks are attached to at the end.
On AROS icons with different sizes result in misalignment and clutter among icons, already square icons at the same size as Round icons, will look large. Also, folders that have edges or protrusions such as handles will appear smaller, this is why I used different sizes for Icon Sets. Best to be aware of misalignment issues with icons. Most icons are 46x46. Folder image area is 42x42 but regular icon image area just like other AROS Glow Icons is 38x38
A note about the used data descriptors that are used throughout from here. All elements are in Motorola byte order (highest byte first):
There are lots of elements marked with ???. These are usually filled with values, which have no effect at all. Thus they can normally be ignored. For some values the usual contents is described.

### OS1.x/OS2.x format

The OS1.x/OS2.x format is storage of the in-memory structures on disk. This text tries to show which values are important and which are not.
This is followed by certain other data structures:
Now a description of the sub-formats:
a) The text storage method (DefaultTool, ToolWindow and ToolTypes):
This means the text "Hallo" will be encoded as \00\00\00\06Hallo\00.
As ToolTypes are an array of texts the encoding is preceded by another ULONG value containing the number of entries. But to make parsing more interesting it is not the number as one would expect, but the number of entries increased by one and multiplied by 4. Thus 10 entries will have 44 as count.
b) The Gadget structure:
c) The DrawerData structure: This structure is useful for drawers and disks (but there are some icons of other types, which still have these obsolete entries).
d) The NewWindow structure used by DrawerData:
e) The DrawerData2 structure for OS2.x drawers:
f) And now the last element, the Image structure:
This is followed by the image data in planar mode. The width of the image is always rounded to next 16bit boundary. loads an ILBM file to get the chunky image data which consists of index values. The image data is processed by RemapIconImage which maps the index values to a standard 4-color palette. Write_Image then writes the planar data to file.

### NewIcon extension

As the original classic icon format is very limited when using more than the 4 or 8 default colors and also when using different palette sets than the default, there have been ideas how to circumvent this. A Shareware author invented NewIcons format, which uses the ToolTypes to store image data, as expanding the original format very surely would have broken compatibility.
The NewIcons stuff usually starts with following 2 ToolTypes text (text inside of the "" only):
"*** DON'T EDIT THE FOLLOWING LINES!! ***"
Afterwards the image data is encoded as ASCII. The lines for first image always start with "IM1=". If present the second image starts with "IM2=".
The first line of each image set contains the image information and the palette.
Afterwards the encoded palette is stored. Each element has 8 bit and colors are stored in order red, green, blue. The encoded format is described below. The ni_Width and ni_Height maximum values are 93. The maximum color value is theoretically 255. I have seen images with at least 257 stored colors (but less than 256 used).
The following lines contain the image data encoded with the same system as the palette. The number of bits used to encode an entry depends of the number of colors (6 colors f.e. need 3 bit). The lines have maximum 127 bytes including the "IM1=" or "IM2=" header. Thus including the zero byte, the string will be 128 byte.
En/Decoding algorithm:
Opposite to the original icon format, the NewIcons format uses chunky modus to store the image data.
The encoding for images and palette stops at the string boundary (127 bytes) with buffer flush (and adding pad bits) and is restarted with next line.

### OS3.5 extension

The original inventor of NewIcon format was Phil Vedovatti. And the one responsible for designing the Glow Icons used with Amiga OS 3.5/3.9 was Mat Chaput.
The OS3.5 format introduces nearly the same information as in NewIcons, but in a more usable format. The tooltypes are no longer misused, but a new data block is appended at the end of the icon file. This data block is in IFF format.
Those files consist of a classic info disk structure (might or might not contain a newicon structure in the tool-types), followed by an IFF icon structure (the actual glowicon bits).
A GlowIcon is thus an IFF structure with a ICON identifier which can contain the (newly added) chunks FACE and IMAG. The file may or may not contain multiple IMAG chunks (though a minimal of 1 and maximum of 2 makes sense in this context).
It consists of the standard header
Now Chunks of different data follow. Each chunk consists of 8 header bytes and the data bytes. If the size in header is uneven, then it is automatically padded with 1 byte at the end.
Currently 3 chunks are used with following data. Note that IFF generally allows expansion and chunk reordering, so do not rely on any current size information or chunk order, but skip unknown data based on the size information stored in file.
1)
2) Now 2 chunks of this type may come, where first chunk is image 1 and second chunk is image 2.
Now about the run-length compression. This is equal to the run-length method in IFF-ILBM format: The input data is seen as a bit-stream, where each entry has im_Depth bits for image or 8 bits for palette. First comes an 8 bit RLE block with following meaning:
In uncompressed mode, each byte represents one pixel (even if lower depth is used).
When saving Classic Icons we are only concerned with the IFF icon images. The IFF Data starts with "FORM....ICONFACE". Save the ILBM file as the actual number of bitplanes & index values & colormap from the icon data. Once you extract the images & colormap it's easy to write the ILBM. To make it easier ILBM can be uncompressed planar images & colormap. There is information for ILBM format if you search for IFF85.
Sometimes Classic Amiga Icons contain OS3.5 IFF Data & ARGB data chunks attached to the end of the file. methods to read the zlib compressed 32bit data.
The IFF data should contain two IMAG chunks for images but it could contain one or none. If it contains only one image we only export one image. If it contain no IMAG chunks for images but it contains one or two ARGB chunks attached to the end of the IFF data then it's an OS4 icon which is a Classic Amiga Icons with the OS3.5 Extension without IMAG but ARGB instead. If it contains one or two IMAG & one or two ARGB chunks then it is an AROS ARGB Icon format.
To decode the image data for IMAG chunks for Glow Icon Format. The image data decoder and RLE decoder are working
Having traced the CybergraphX ReadRGBPixel function. It uses DoPixelFunct which then reverts to do_pixel_funct which is part of Rom/Graphics. ReadPixel only uses RGB values.
If a sample pixel that is (255,46,58,78). It's an ARGB 32 bit pixel. Yet ReadRGBPixel returns 3029582 which is 2E3A4E or in decimal it is 46,58,78. So the alpha is missing. It's only RGB. That makes sense because it uses the same function as ReadPixel.
Something strange happens when reading alpha pixels (less than 255). The color (12,0,0,0) has an alpha of 12 but ReadRGBPixel returns (146,146,146). So it seems that ReadRGBPixel uses Premultiplied Alpha with the background color (153 in this case). Part of the mystery is solved. Now can supply a sample value for WriteRGBPixel then go from there.
After evaluating several alpha pixels in the original image and comparing the resulting values from ReadRGBPixel, worked out the Alpha Blending Formula.
If the background color is (153,153,153) and the ARGB pixel is (13,0,0,0) this is the formula:
This is the DrawLargeImage function so far. In the screenshot "pixel buffer" is the byte buffer containing the pixel data from the original image which is the small image. Each ARGB pixel in the original image gets mapped to a region of pixels which are 2x2 in this case since pixelateSize=2.

### PowerIcons PNG

Workbench (Wanderer) does not read anything directly itself - it relies on icon.library for "file" processing. The loading of PNG Icons does not happen using datatype *system*. It's done through libpng functions. To avoid that both icon.library and png.datatype have libpng statically linked in (double file/mem usage), it's done only for one of them: png.datatype. The png.datatype exposes some extra functions PNG_#?. See workbench/classes/datatypes/png/png.conf and directaccess.c in same directory.
In workbench/libs/icon/diskobjPNGio.c you can see how the PNG_ functions are used to read the PNG icon. In there you'll also see a function MakePlanarImage. It's one function which will certainly slow down things a bit. What is does (in very unoptimized way) is to create a very simple realtime remapped planar version of the PNG image(s) to be used on low color (LUT) screens.
merge icon35 and png icons
* png data would live in the IFF stream of the icon35 format (IFF type 'PNG ')
* 4 color and icon35 image formats would be precomputed by the ilbmtoicon tool
* AOS should be able to read and understand this format
The easiest way to split PNG icons & retain the icOn chunk is to find the first 'IEND' & second 'IEND' if there is one then calculate filesize1 & filesize2 then read & write binary. You could use another method to get the images but the icOn chunk may be lost unless you locate it just before 'IEND' then save it to .bin file or store it some other way to later write to file. As far as classic Icons you can just read them sequentially. For AROS we can just use IconControl functions but for Windows or an OS other than AROS you need another method to read the icon data.
Do OS4 and MorphOS use the same type of PNG icons as us, or a different variation? They use the same format (which PowerIcons originated), which is a plain PNG file named "*.info" with some extra PNG hunks in it to hold some icon data. (PNG is like IFF in that way).
Extending the Icon 3.5 to include PNG data, so that (a) our generated ICONs can work on any Amiga system, including OS 1.x to 3.x, and (b) my poor 68000 can choose a planar image from the icon file instead of spending approx 7 seconds per icon converting from ARGB to 4-color planar.
Existing PNG support will *not* be changed - so we should continue to be able to enjoy AmigaOS4 and Morphos icons sets on the faster processors.
png images with special ic0n chunk embedded inside png. can be 1 or 2 png images.
ic0n chunk stores the 'old' data required to fill f.e. a drawerdata structure.
it is a taglist that can contain zero or more tags from the following list:
Of course, each tag followed by its respective value.

## Handling

Handling of icons by an AppWindow/Menu/Icon. That's how the concept of graphically dealing with files (represented as icon objects) from an already running application was implemented from Kickstart 2.04 on. So selecting icons isn't enough for any application to be aware of it: the user has to do one more action (which is to drag the selected icon(s) towards an AppWindow/Icon or to select an AppMenu).
Wanderer only allows to use AppWindows yet. So promote your window as an AppWindow, then listen to the AppMessage and act accordingly.
If you want to act on more than one icon at a time, you will need to adapt the code to browse AppMessage->am_ArgList as many times as AppMessage->am_NumArgs ...
Our "DefaultIcon" implementation was better (and more like the original) - it would be easy to add default Icons that use pattern matching rather than the less efficient datatype matching.
If the icon is associated with a directory (WBDISK, WBDRAWER, WBGARBAGE), it needs a DrawerData structure to go with it. This structure contains an Intuition NewWindow structure [...] Workbench uses it to hold the current window position and size of the window so it will reopen in the same place.
for a directory, the icon is stored in a .info file at the same level where the directory name appears (not in the directory itself). The icon type should be set to DRAWER. The icon for a disk should always be stored in a file named disk.info at the root level directory of the disk. The icon type should be set to DISK. (The icon type can be set and the icon imagery edited with the IconEdit program.)
So it is clear that an Amiga disk named "foo" contains a file named "disk.info" at the root: here is the imagery of the icon of the disk (seen on the main Workbench window and associated with the name "foo"), and here is also the coordinates of the window to be opened when the user double-clicks on it. If the disk contains a drawer named "bar" with an icon, you can use "C:List foo:" to be able to read the content which should at least include "bar" (which is the drawer itself) and "bar.info" (which contains the drawer icon imagery (seen in the foo window on workbench screen) _and_ the coordinates of the window to be opened when the user double-clicks on this bar icon). Of course it is possible to have disks without icons, and drawers without icons: in such cases, Workbench can provide default ones (and always do for disks).
AFAIK Amiga icons are handled like that:
Open them doing something like
and then you can for example read the coordinates of the icon by
and if it's the icon of a drawer or of a disk (then the info file contains a DrawerData structure), you can read the coordinates of the window to open when double-clicking on the icon:
If it's a drawer (or disk) icon designed for OS2+, it contains Flags and ViewModes in DrawerData structure that store the way icons are shown in the drawer's window: you can read it by something like:
The default icons to specify possible operations for an Icon (thereby filetype) via the default icons tooltypes. The normal Icon behaviour would still be used for its default action but it could also expose specific actions for that file type, e.g.

## Tooltype

from http://utilitybase.com/forum/index.php?action=vthread&forum=2&topic=1252
Be very careful with modifying the tooltypeslist in an icon.
* Read in an icon (Icon->GetdiskObject)
* Build a new tooltypeslist
* Copy the address of the current tooltypelist to a safe place
* Copy the address of the NEW tooltypeslist to the icon
* Rewrite the icon (Icon->PutDiskObject)
* Copy the address of the old tooltypeslist from the safe place BACK into the icon
* Free the diskobject (Icon->FreeDiskObject)
6 and 7 are not actually necessary. icon.library keeps track of all the data associated with a loaded icon through a mechanism attached to the 'struct DiskObject' itself, in the private undocumented part of the structure. It does not follow the pointers or assume that they point somewhere meaningful.
In essence, this means that you can modify every bit of information in the documented portion of the 'struct DiskObject' without ill effects. But you have to be careful that the information is in itself consistent if you want to write it back to disk. While icon.library does perform some sanity checking, especially icon.library V44 and beyond, there is only so much you can do.
Applications generally want to call GetDiskObjectNew -- rather than GetDiskObject -- to get disk objects for icons dropped in the window

## LayoutIcon

Currently, LayoutIcon is unimplemented, and an idea that could save me a lot of RAM for PNG images, when they are rendered on low-color screens. The idea is to use LayoutIcon to render the icon into the Screen's bitmap layout, and use that as the gadget imagery for the icon, and FreeMem the PNG or other high-color icon imagery.
This is similar to how AOS does things, but with one trick - I 'remember' what image format (and offset and size in the .icon file) was originally there, and when PutDiskObject is called I carefully avoid scribbling on the image data, preserving the original image.
But you need update the images, when a user change the screen depth. In AFA layoutIcon is too unimplement, i add some times before a jump in debugger command when function is called to test.if a program use this function.I see that workbench not use this function.also other programs do not use. But a speedup of AROS iconlib and much less memory usage is possible, when you make a cache, so that all default Icons only load once.getdiskobject give then only a pointer to existing default icon.
The problem on AROS is, it load every time the icon in and use new memory. For example if you show 100 jpg files, then 100* the icon def_jpg.info is load.so 100* memory usage and load time usage. As wanderer loads always all icons, even if only icon view is select.

## transparent PNG

graphics.lbrary BltMaskBitMapRastPort is useful

## Datatype Detection

The icon.library uses the datatype descriptors from sys:devs/datatypes to identify the file type. Then a default icon def_NAME.info is used for a file with a type of NAME. The AROS build-system uses the tool createdtdesc to create datatype descriptors from simple text files.

## Bugs

After icons can be moved, it will be good to be able to snapshot their position.
And the position of the window in the drawer icon. But beware that IIRC there is a bug/unimplemented feature somewhere (in icon.library?) that prevents it to store properly DrawerData struct (dd_Flags and dd_NewWindow members) in all cases. So Wanderer suffers of the problem too currently, and you can't both save the "View All Files" state _and_ snapshot the window position of a drawer.
* having a database in the dir containing mappings is also inefficient when working with individual files - perhaps more so than matching using deficons/datatypes (which generally scan the first bytes of a file only). What happens in a large directory and the file you are querying is deep within the database? slower performance..
* modern filesystems can store additional metadata with files - e.g. in NTFS pretty much everything is an attribute of some form or other, it wouldnt take much to make it possible to include querying/setting such attributed as part of most amigaos code's exall/exnext dir scanning loops.
one scenario is some combination of using file system meta data and our default icons.
An application scans a directory of files using the normal AmigaOS routines. we provide a new routine (*) to query a file/locks attributes (which uses packets to speak with the file system handler and query the meta data) which we use to request the data formats attribute. This shouldn't incur any/much IO penalty since the meta data is most likely already cached as part of scanning the dir. if the attribute isn't available we can then use default icons pattern/data matching to identify the file - and optionally then set the attribute if the file system does support meta-data.
(*) perhaps this call could be handled in the deficon code itself anyhow, so that existing amigaos code that uses icon.library, etc, would benefit from it without need for change.

## Examples

The problem with an SVG based icon is that's there's no place to store the icon data itself. In PNG icons they use an icOn chunk. Classic Icons store icon attributes in the diskobject data, etc. But SVG would have to be a hybrid icon. Classic Amiga Icon File at the beginning. Where the IFF data for a Glow Icon would normally be is instead the beginning of the SVG data. How many images can it store?
SVG is a very flexible format because it allows to embed vector, bitmap and text content, and transformations / filters / animations, so you don't even need to define something like dual PNGs (one SVG should be enough to emulate it). SVG allows to define metadata of any kind, that can be used to store the icon attributes (and much more). You can add those tags everywhere (AFAIR), so even at beginning of the XML data (this can be "forced" as a requirement for those new icons, if it's needed).