[id] = CreateIcon(id, table)

By using individually designed images for each size instead of just scaling one and the same image to each size, a better quality is achieved, especially when it comes to smaller image sizes, which look much better when they are specifically designed for their resolution. Typical sizes for the individual images within an icon are 16x16, 24x24, 32x32, 48x48, 64x64, 96x96, 128x128, 256x256, and 512x512, but they can also be completely arbitrary. The advantage of having the same image in different sizes in an icon is that Hollywood can choose an appropriate size depending on the screen resolution.

Furthermore, images inside Hollywood icons can also be specifically designed for different color depths. For example, you can provide 24x24 images in various color depths, e.g. in 256 colors (8 bits) and in true color with alpha channel (32 bits). Thus, it is possible to have images of the same size inside an icon as long as they differ in their color depth. This once again gives Hollywood the advantage of choosing the best image from an icon for a certain screen resolution and color depth.

Finally, each image inside an icon set can have two different states: normal and selected. Normally, you only ever need the normal state, but on AmigaOS and compatibles the selected state is sometimes used as well.

On top of the identifier for the new icon that is to be passed in id, you also have to pass a table in the table parameter to CreateIcon(). This table must contain a number of subtables, one for each image size you wish to add to the icon.

The individual subtables can use the following tags:

Type:

This tag allows you to set the source type of the image you wish to add to the icon. This can be #BRUSH if you want to add a brush, or #FILE if you would like to add an image from an external file source. The default is #BRUSH. Note that that default is different to the default used by the @ICON preprocessor command, which is #FILE.

Image:

This tag specifies the actual image source and must be set in every subtable. If Type has been set to #BRUSH, you have to set this tag to the identifier of a brush you want to add to the icon. The brush can be an RGB or palette brush. Otherwise, Image needs to be set to the path of an image file that should be added to the icon. The image file may be in any of the image file formats supported by Hollywood. Note that if the image file specified here has an alpha channel, the alpha channel data is loaded automatically. If it is a palette image and the LoadPalette tag is set to True (see below), the image's transparent pen will also be loaded automatically. Also note that in every icon, each image size must only be used once for each color depth, i.e. it is not possible to add two 48x48 images that use the same color depth to a single icon. There can only be one image for each size and color depth in every icon. Note that if the image you specify here is in a vector graphics format, i.e. either a vector brush or a file in a vector image format, you mustn't pass any other images because in the case of vector graphics, one image is used for all sizes and Hollywood will automatically render it to all sizes it needs. So if you use vector instead of raster graphics, there must only be one subtable in the table you pass to CreateIcon().

SelImage:

This tag allows you to include an additional image that should be used as a selected version of the image specified in Image. This tag is optional. If you set it, the image specified here must be of exactly the same size as the one specified in Image. Besides that, SelImage is used in the very same way as Image, i.e. it depends on the image type set in Type what you have to pass here, either a brush identifier or a path to an external image file.

Standard:

This tag allows you to set the image specified in this subtable as the standard size for the icon. Setting a standard size is important in some contexts, so that Hollywood knows which image to pick for higher resolutions, e.g. if you designate a 64x64 image inside an icon as the standard size, Hollywood knows to pick the 128x128 image in case the monitor's resolution uses a DPI setting that is twice as high as the normal setting. Obviously, there can be only one standard image inside every icon, so setting this tag to True twice will result in an error. Also note that it is not necessary to declare a standard icon size, but for many use cases it is recommended to do it.

Loader:

This tag allows you to specify one or more format loaders that should be asked to load the image files specified in Image and SelImage. If specified, this must be set to a string containing the name(s) of one or more loader(s). Defaults to the loader set using SetDefaultLoader(). See Loaders and adapters for details. Obviously, this tag is only used when Type is set to #FILE.

Adapter:

This tag allows you to specify one or more file adapters that should be asked to open the files specified in Image and SelImage. If specified, this must be set to a string containing the name(s) of one or more adapter(s). Defaults to the adapter set using SetDefaultAdapter(). See Loaders and adapters for details. Obviously, this tag is only used when Type is set to #FILE.

LoadPalette:

If this tag is set to True and Type is set to #FILE, Hollywood will try to load the image's palette and store the image as a palette image within the icon. If the image has a transparent pen, that transparent pen will be loaded automatically. (V9.0)

This command is also available from the preprocessor: Use @ICON to create icons from the preprocessor.

To add and remove individual images from an icon, use the AddIconImage() and RemoveIconImage() functions.

id

identifier for the icon or Nil for auto id selection

table

table containing the individual images to be added to the icon (see above)

CreateIcon(1, {
    {Image = "ic16x16.png", Type = #FILE},
    {Image = "ic24x24.png", Type = #FILE},
    {Image = "ic32x32.png", Type = #FILE},
    {Image = "ic48x48.png", Type = #FILE},
    {Image = "ic64x64.png", Type = #FILE},
    {Image = "ic96x96.png", Type = #FILE},
    {Image = "ic128x128.png", Type = #FILE},
    {Image = "ic256x256.png", Type = #FILE},
    {Image = "ic512x512.png", Type = #FILE},
    {Image = "ic1024x1024.png", Type = #FILE}})

CreateIcon(1, {{Image = "icon.svg", Type = #FILE}})