Name
SaveIcon -- save icon to disk (V9.0)
Synopsis
int ok = SaveIcon(STRPTR filename, struct hwIconList *list, struct
             hwTagList *tags);
Function
This function must save the icon to the specified filename. The icon's images are passed to SaveIcon() in the form of a struct hwIconList that contains one node per image.

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.

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

Inputs
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
Results
ok
True or False indicating success or failure

Show TOC