NAME
        LayoutIconA -- Adapt a palette-mapped icon for display (V44)

   SYNOPSIS
        success = LayoutIconA(icon,screen,tags);
        D0                    A0   A1     A2

        bool layouticona(struct diskobject *icon,struct screen *screen,
                         struct tagitem *tags);

        success = LayoutIcon(icon,screen,...);

        bool layouticon(struct diskobject *icon,struct screen *screen,...);

   FUNCTION
        This function will prepare an icon for display, either on a
        specific screen or using a default colour palette. It is
        useful only for palette mapped icons.

   INPUTS
        icon -- The icon to be remapped. This must be a palette mapped
            icon.
        screen -- Pointer to a screen to remap the icon for or NULL
            to remap the icon to use the system default colour palette
            or something very similar to it (this means: four colours
            only).
        tags -- Additional rendering options.

   TAGS
        OBP_Precision (LONG) -- Pen colour allocation precision.
            Default is the same precision as set in the global
            icon.library settings (see iconcontrola()).

   OUTPUTS
        success -- TRUE if the icon could be remapped, FALSE if
            the remapping failed for some reason. In case of
            of failure, icon.library will try its best to keep
            the icon in a presentable state, but this may fail.
            In case of failure, the error code can be retrieved
            using dos.library/ioerr.

   NOTES
        You must make sure that the screen you remap to does not
        go away while there is an icon to use its colours. For
        a public screen, the easiest way to guarantee this is
        to keep it locked (see intuition.library/LockPubScreen).
        For custom screens, just don't close them! If you have to close
        the screen or need to keep your icon around until after a screen
        is closed, you should call LayoutIcon() with a NULL screen
        parameter. This will release all pens the icon has allocated
        and remap the icon to a default set of colours. Alternatively,
        you can dispose of the icon via freediskobject() which
        will also release all pens the icon has allocated, including
        the icon itself, of course.

        Icons remapped to the global default screen (normally, that
        would be the Workbench screen) may get changed and remapped
        again during Workbench close/open transitions. To prevent
        this from taking place, just make sure that the Workbench
        screen does not close (e.g. via LockPubScreen("Workbench")).

   SEE ALSO
        dos.library/ioerr
        graphics.library/obtainbestpena
        graphics.library/releasepen
        icon.library/freediskobject
        icon.library/geticontaglist
        icon.library/IconControl
        intuition.library/lockpubscreen
        intuition.library/unlockpubscreen
        graphics/view.h