With an image structure an application can create graphic objects quickly
and easily and display them almost anywhere.  Images have an additional
attribute that makes them even more economical--by changing two simple
data elements in the Image structure, the color of the image may be
changed.

Images are rectangular bitmaps which individually define the color of each
pixel represented.  Images may not be masked to allow part of the
background to show through.  The entire rectangular image is drawn into
the target element, overwriting any data it may overlap.  All bitplanes
defined in the target rastport within the image's rectangle are
overwritten either with image data, ones or zeros.

images may be directly drawn by the application by using the drawimage()
function, described below.  The image may be rendered into any screen or
window rastport with this function.  (drawimagestate() can also be used to
draw the image.

The visual imagery for an image can be removed from the display by calling
eraseimage().  for a normal image structure, this will call the graphics
function eraserect(), which clears the image rectangle by using the
layer's backfill pen to overwrite it.

Alternately, images can be used indirectly by attaching them to menus,
gadgets or requesters when they are initialized.  For instance, in menus
the menuitem structure has the itemfill and selectfill fields.  if the
itemtext flag is cleared and the highimage flag is set, the application
may place a pointer to a list of image structures in each of these fields.
The system will display the ItemFill images when the menu item is not
selected and the SelectFill images when the menu item is selected.  The
application does not have to take any specific action to display these
images.  Once the menus have been added to a window, their management and
display is under Intuition control.

The number of bitplanes in an image does not have to match the number of
bitplanes in the display element in which the image is rendered.  This
provides great flexibility in using image structures, as the same image
may be reused in many places.

If the application's window is on the Workbench or some other public
screen, it must use caution with hard-coded or constant image data, as the
color palette of that screen is subject to change.  If the application has
its own custom screen, and it is appropriate for the colors of that screen
to change, the same situation arises.  Starting with V36, Intuition allows
the screen opener to provide a mapping of pen number and rendering
functions.  For example, pens are specified for the bright and dark edges
of three dimensional objects.  Applications can obtain this mapping from
the drawinfo structure.  see the "intuition screens" chapter for more
information on DrawInfo and the new 3D look of Intuition in Release 2.

A suitably designed image may be drawn into a screen or window of any
depth.  To accomplish this, the application must ensure that detail is not
lost when the image is displayed in a single bitplane rastport, where only
the first bitplane of image data will be displayed.  This is important if
the image will ever be displayed on the Workbench screen or any other
public screen.

 image structure               picking bitplanes for image display 
 directly drawing the image    image example 
 image data