int ok = SaveIcon(STRPTR filename, struct hwIconList *list, struct
             hwTagList *tags);

struct hwIconList looks like this:

struct hwIconList { struct hwIconList *Succ; APTR Data; int Width; int Height; ULONG Flags; ULONG *Palette; ULONG TransPen; int Depth; APTR UserData; };

For each node in the list, struct hw_IconList will be initialized as follows:

Succ:

Will be set to a pointer to the next list node or NULL if this node is the last one.

Data:

Will be set to the image's pixel data. For RGB images, this will be set to a 32-bit ARGB pixel buffer, for CLUT images to an 8-bit pixel buffer. For 32-bit images the alpha byte will always be set for every pixel. For CLUT images, the Palette member (see below) will be set. The pixel buffer's size will be exactly width * height * bpp. No row padding will be used.

Width:

Contains the image's width in pixels.

Height:

Contains the image's height in pixels.

Flags:

May be set to a combination of flags for this image. The following flags are currently supported:

HWICONFLAGS_DEFAULT:

This flag marks the default icon. Hollywood's icon type allows scripts to designate an icon as the default one. It's up to you how you interpret and handle the default icon.

HWICONFLAGS_SELECTED:

If this flag is set, the image in this list node describes a selected icon state. On AmigaOS and compatibles, icon images usually have two states: normal and selected. This flag will be used to mark an image as the selected image.

HWICONFLAGS_OPAQUE:

This flag will be set if the image doesn't use any transparency and all alpha bytes are set to 255 (i.e. visible).

Palette:

If the image is a CLUT image, this will be set to a pointer to an array of ULONGs which contains the palette colors for the image. The palette colors are stored as raw RGB values.

TransPen:

If the image is a CLUT image and has a transparent pen, this member will be set to the pen that should be transparent. If there is no transparent pen, this will be set to HWPEN_NONE.

Depth:

This will be set to the image's depth. This will be a bit depth either between 1 and 8 for CLUT images or 32 for RGB images with alpha channel.

The tags argument will be set to a tag list that can contain the following tags:

HWSVICONTAG_FORMAT:

This tag contains the identifier of the icon format the file should be saved in. You only need to handle this tag if your plugin supports more than one output icon format. Nevertheless, this tag will always be present.

HWSVICONTAG_COMPRESSION:

Hollywood's SaveIcon() function allows scripts to specify a compression level between 0 and 100 because some icon formats might use lossy compression. HWSVICONTAG_COMPRESSION will simply forward the specified compression level to your plugin.

HWSVICONTAG_AMIGAEXT:

If this tag is present, the pData member of it will be set to a struct hwIconAmigaExt pointer. This structure is used for storing metadata that is present in every Amiga icon. See LoadIcon for a detailed description of this structure.

HWSVICONTAG_ADAPTER:

Starting with Hollywood 10.0, users can specify the file adapter that should be used to save an icon. If this tag is set, Hollywood wants your plugin to use the file adapter specified in the pData member of the tag to save the icon. This means that you have to use hw_FOpenExt() instead of hw_FOpen() to save the icon. See hw_FOpenExt for details. (V10.0)

HWSVICONTAG_USERTAGS:

If this is set, pData will point to a struct hwUserTagList containing a list of user tags passed by the Hollywood script. User tags are a way of passing additional information from Hollywood scripts to plugin functions. Note that even if your plugin doesn't support any user tags, you should still look for this tag and pass the user tags to hw_FOpenExt because the user tags passed in UserTags could also be intended for another plugin, namely the file adapter plugin passed in Adapter. See User tags for details. (V10.0)

This function has to return True if the image has been successfully saved or False in case of an error.

filename

path to a destination file

list

linked list of all images that should be saved to the icon

tags

tag list containing further parameters

ok

True or False indicating success or failure