struct hwIconEntry *icon = hw_GetIconForDensity(lua_ID *id, double
                        *density, ULONG flags, struct hwTagList *tags);

The flags parameter can be used to configure how hw_GetIconForDensity() should behave when scanning the icon for images. The following flags are currently defined:

HWGIFDFLAGS_SELECTED:

Set this flag if you want hw_GetIconForDensity() to return the selected image instead of the normal image. If this flag is set and there is no selected image, hw_GetIconForDensity() will fail.

HWGIFDFLAGS_NOSCALE:

By default, hw_GetIconForDensity() will scale images if they don't exactly fit the required density. If you don't want this behaviour, you can set HWGIFDFLAGS_NOSCALE to prevent hw_GetIconForDensity() from scaling images. Note, however, that in this case the image returned by hw_GetIconForDensity() might not be an exact match for the specified density.

HWGIFDFLAGS_INTERPOLATE:

By default, hw_GetIconForDensity() will scale images if they don't exactly fit the required density. If you set this flag, interpolation will be used when scaling images. It is recommended to set this tag because images typically look much better with interpolated scaling.

HWGIFDFLAGS_MUSTMATCH:

Set this flag if hw_GetIconForDensity() should only accept images which match the specified density exactly. If there is no exact match, hw_GetIconForDensity() will return NULL.

hw_GetIconForDensity() will return a pointer to a struct hwIconEntry which looks like this:

struct hwIconEntry { APTR Data; int Width; int Height; ULONG Flags; ULONG *Palette; // V9.0 ULONG TransPen; // V9.0 int Depth; // V9.0 };

Here is a description of the structure members of struct hwIconEntry:

Data:

This will be set to a 32-bit ARGB pixel buffer containing the image data of this item. The alpha byte will always be set for every pixel. The pixel buffer's size will be exactly width * height * 4. No row padding will be used. The pixel buffer pointer will be valid until you call hw_FreeIcon().

Width:

Contains the image's width.

Height:

Contains the image's height.

Flags:

This contains 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 is a selected icon state. On AmigaOS and compatibles, icon images usually have two states: normal and selected.

HWICONFLAGS_OPAQUE:

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

HWICONFLAGS_EXTENDED:

This flag is set if struct hwIconEntry has the structure extensions introduced in Hollywood 9.0. Before you access any of those extensions, e.g. the Palette or Depth members, you must either check if this flag is set or if the Hollywood version that opened your plugin is at least 9.0. (V9.0)

Palette:

This will always be NULL because hw_GetIconForDensity() currently won't return palette images. (V9.0)

TransPen:

This will always be HWPEN_NONE because hw_GetIconForDensity() currently won't return palette images. (V9.0)

Depth:

This will always be 32 because hw_GetIconForDensity() currently won't return palette images. (V9.0)

The image that is returned by this function must be freed using the hw_FreeIcon() function. See hw_FreeIcon for details.

id

object identifier of icon to use

density

pointer to a double containing the desired density or NULL to use the current monitor's default density

flags

flags that specify how hw_GetIconForDensity() should behave (see above)

tags

reserved for future use; pass NULL

icon

icon image that is best optimized for the specified density or NULL on error