NAME
	picture.datatype -- the root data type for pictures.

   FUNCTION
	The picture.datatype is the super-class for any picture related
	classes.

   METHODS
	OM_NEW -- Create a new picture object.

	OM_GET -- Obtain the value of an attribute.

	OM_SET -- Set the values of multiple attributes.

	OM_UPDATE -- Update the values of multiple attributes.

	OM_DISPOSE -- Dispose of a picture object.

	GM_LAYOUT -- Layout the object and notify the application of the
	    title and size.

	GM_HITTEST -- Determine if the object has been hit with the
	    mouse.

	GM_GOACTIVE -- Tell the object to go active.

	GM_HANDLEINPUT -- Handle input.

	GM_RENDER -- Cause the graphic to render.

	DTM_PROCLAYOUT -- Layout (remap) the picture on the application's
	    process.

	DTM_FRAMEBOX -- Obtain the display environment that the picture
	    requires.

	DTM_SELECT -- Select an area in the picture.

	DTM_CLEARSELECTED -- Deselect the selected area of the picture.

	DTM_COPY -- Copy the selected area of the picture to the clipboard
	    as an ILBM.  If no area is selected, then the entire picture
	    is copied.

	DTM_PRINT -- Print the selected area of the picture.  If no area
	    is selected, then the entire picture is printed.

	DTM_WRITE -- Write the selected area of the picture to a file as an
	    ILBM.  If no area is selected, then the entire picture is
	    saved.

	PDTM_WRITEPIXELARRAY -- Transfer pixel data to the picture
	    object. Requires that PDTA_SourceMode==PMODE_V43, as
	    described below. (V43)

	PDTM_READPIXELARRAY -- Transfer pixel data from the picture
	    object. Requires that PDTA_DestMode==PMODE_V43, as
	    described below. (V43)

   TAGS
	OBP_Precision (ULONG) -- Precision to use when obtaining colors.
	    See the PRECISION_[..] defines in <graphics/view.h>.
	    Applicability is (I). Defaults to PRECISION_IMAGE.

	PDTA_ModeID (ULONG) -- Set and get the graphic mode id of the
	    picture (see <graphics/modeid.h>).

	    Applicability is (ISG).

	PDTA_BitMapHeader (struct BitMapHeader *) -- Get the
	    base information for the picture.  BitMapHeader is defined in
	    <datatypes/pictureclass.h>

	    Applicability is (G).

	PDTA_BitMap (struct BitMap *) -- Pointer to a class-allocated
	    bitmap, that will end up being freed by the picture class in the
	    OM_DISPOSE method.

	    Applicability is (ISG).

	PDTA_ColorRegisters (struct ColorRegister *) -- Color table; its
	    contents should match the colours in the PDTA_CRegs table.

	    Applicability is (G).

	PDTA_CRegs (ULONG *) -- Color table to use with SetRGB32CM().

	    Applicability is (G).

	PDTA_GRegs (ULONG *) -- Color table; this table is initialized
	    during the layout process and will contain the colours the
	    picture will use after remapping. If no remapping takes
	    place, these colours will match those in the PDTA_CRegs table.

	    Applicability is (G).

	PDTA_ColorTable (UBYTE *) -- Shared pen table; this table is
	    initialized during the layout process while the picture
	    is being remapped.

	    Applicability is (G).

	PDTA_ColorTable2 (UBYTE *) -- Shared pen table; in most places
	    this table will be identical to the PDTA_ColorTable table.
	    Some of the colours in this table might match the original
	    colour palette a little better than the colours picked for
	    the other table. The picture.datatype uses the two tables
	    during remapping, alternating for each pixel.

	    Applicability is (G).

	PDTA_Allocated (ULONG) -- OBSOLETE; DO NOT USE

	PDTA_NumColors (UWORD) -- Number of colors used by the picture.

	    Applicability is (ISG).

	PDTA_NumAlloc (UWORD) -- Number of colors allocated by the picture.
	    In this context `allocated' refers to colours allocated via
	    graphics.library/ObtainBestPenA.
	    Applicability is (G).

	PDTA_Remap (BOOL) -- Indicate whether the picture should be
	    remapped or not.

	    Applicability is (I). Defaults to TRUE.

	PDTA_Screen (struct Screen *) -- Pointer to the screen to remap
	    the picture to.  Only used if the object is not going to be
	    added to a window.

	    Applicability is (IS). Defaults to NULL.

	PDTA_FreeSourceBitMap (BOOL) -- Indicate whether the source
	    bitmap should be freed immediately by the picture.datatype
	    after the GM_LAYOUT method is called.

	    Applicability is (IS). Defaults to FALSE.

	PDTA_Grab (Point *) -- Pointer to a Point structure, that
	    defines the grab point of the picture.

	    Applicability is (ISG).

	PDTA_DestBitMap (struct BitMap *) -- Pointer to the remapped
	    bitmap.

	    Applicability is (G).

	PDTA_ClassBitMap (struct BitMap *) -- Pointer to the BitMap
	    allocated by the subclass (e.g. ilbm.datatype) which read
	    the picture. picture.datatype will never free this bitmap,
	    the subclass is responsible for doing this.

	    Applicability is (ISG).

	PDTA_NumSparse (UWORD) -- Number of entries in the sparse color
	    table.

	    Applicability is (I). Defaults to 0.

	PDTA_SparseTable (UBYTE *) -- Pointer to a table of pen numbers
	    indicating which colors should be used when remapping the
	    picture.  This array must contain as many entries as indicated
	    by the PDTA_NumSparse tag.

	    Applicability is (I). Defaults to NULL.

	PDTA_SourceMode (LONG) -- Used by subclass implementors only; this
	    tag determines whether the picture.datatype expects a bitmap
	    as the input parameter (PMODE_V42) or accepts PDTM_WRITEPIXELARRAY
	    messages instead (PMODE_V43).

	    Applicability is (ISG). Defaults to PMODE_V42. (V43)

	PDTA_DestMode (LONG) -- Used by application software writers only;
	    this tag determines whether the picture.datatype will return
	    only standard format BitMaps (PMODE_V42) or whether it will
	    return BitMaps about whose memory layout the caller should
	    not speculate (PMODE_V43). If set to PMODE_V43, you must not
	    examine the contents of the BitMap you receive from
	    picture.datatype.

	    Applicability is (ISG). Defaults to PMODE_V43. (V43)

	PDTA_UseFriendBitMap (BOOL) -- If set to TRUE, all BitMap
	    allocations done by picture.datatype will be done with
	    a friend BitMap as a reference (see graphics.library/AllocBitMap).

	    Applicability is (ISG). Defaults to TRUE. (V43)

	PDTA_MaskPlane (PLANEPTR) -- Pointer to a bit plane suitable
	    for use with BltMaskBitMapRastPort(), or NULL if the
	    picture has no transparent colours.

	    Applicability is (G). Defaults to NULL. (V43)

	PDTA_WhichPicture (ULONG) -- Index number of the picture to load.
	    For several pictures to be stored in the same file, index
	    number 0 would refer to the first picture, index number 1 would
	    refer to the second picture, etc. This tag works together with
	    the PDTA_GetNumPictures tag. To load a specific picture from
	    a file, first check how many pictures there are. This is done
	    by asking the picture.datatype subclass to load the first
	    picture and also to count the number of pictures, like this:

	        Object * picture;
	        ULONG numPictures;

	        /* Note: you must always initialize this value
	         *       prior to querying the number of pictures
	         *       stored in a file.
	         */
	        numPictures = PDTANUMPICTURES_Unknown;
	        picture = NewDTObject(...,
	                      PDTA_WhichPicture,0,
	                      PDTA_GetNumPictures,&numPictures,
	                      ...
	                  TAG_DONE);

	        /* Now check if there is more than a single picture
	         * in this file.
	         */
	        if(numPictures != PDTANUMPICTURES_Unknown &&
	           numPictures > 1)
	        {
	            Object * secondPicture;

	            picture = NewDTObject(...,
	                          PDTA_WhichPicture,1,
	                          ...
	                      TAG_DONE);

	            ...
	        }

	    Older picture.datatype subclasses may not support the
	    PDTA_WhichPicture and PDTA_GetNumPictures tags. The only way
	    to find out is by using the query tag PDTA_GetNumPictures.
	    If the subclass supports both the PDTA_GetNumPictures and
	    PDTA_WhichPicture tags, it will modify the value stored in
	    the variable passed with PDTA_GetNumPictures.

	    If the requested picture is unavailable (e.g. you might ask
	    for picture #10, whereas there are only three pictures in a
	    file) the subclass will return NULL and set the error
	    code DTERROR_NOT_AVAILABLE. This does not signify that the file
	    in question was not found, it just tells you that the picture
	    with the requested index number is not available.

	    Note that for older picture.datatype subclasses, the
	    PDTA_WhichPicture tag will be ignored. No matter which value
	    you supply, you will always receive the first picture stored
	    in the file.

	    Applicability is (I). Defaults to 0. (V44)

	PDTA_GetNumPictures (ULONG *) -- Query the number of pictures
	    stored in a file. For an example of its use, see the description
	    for the PDTA_WhichPicture tag.

	    Note that older picture.datatype subclasses will ignore this
	    tag. Consequently, the variable you pass in may not be modified.
	    Therefore you should initialize it to the constant value
	    PDTANUMPICTURES_Unknown before you pass it to NewDTObject().

	    This tag is unusual in that it does not operate on an already
	    existing object in the GetDTAttrs() context. This was done for
	    practical reasons, i.e. while the picture.datatype subclass is
	    still processing the image data it may be much more convenient
	    to count the number of pictures in a file than it would be later
	    when the file has already been read.

	    Applicability is (I). Defaults to NULL. (V44)

	PDTA_MaxDitherPens (ULONG) -- Maximum number of pens to use during
	    colour quantization.

	    Applicability is (ISG). Defaults to 125. (V44)

	PDTA_DitherQuality (ULONG) -- Quality of the dithering algorithm to
	    be used during colour quantization. A value of 0 yields no or
	    only little picture quality improvement while a value of 2 will
	    yield noticeably better picture quality. Generally, the higher
	    the quality you demand, the better the output will look like.

	    Applicability is (ISG). Defaults to 1. (V44)

	PDTA_AllocatedPens (UBYTE *) -- Get the pointer to the table of
	    allocated pens. Each entry stands for the pen assigned to the
	    colour of the corresponding palette entry. Please note that
	    you may receive NULL as a return value instead of a pointer
	    and that the table may not hold any valid information unless
	    the value returned with the PDTA_NumAlloc tag is greater
	    than zero.

	    Applicability is (G). (V44)

   NOTES
	The PDTA_Allocated tag should not be used since it was never
	implemented in any way the documentation suggested.

	picture.datatype V44 no longer suffers from the layout restrictions
	present in older picture.datatype revisions. This means for example,
	that for an extra-halfbrite picture you need no longer open a
	custom screen to display it. Any screen will do. The same holds
	true for hold-and-modify pictures.

	Writing greyscale data to a picture (via the PBPAFMT_GREY8 pixel
	format and the PDTM_WRITEPIXELARRAY method) automatically
	configures the picture colour palette when the first line is
	written. The palette is reset to 256 shades of grey with 0 = black
	and 255 = white. If you do not want this to happen, do not use the
	PBPAFMT_GREY8 pixel format: use PBPAFMT_LUT8 instead. This will
	give you complete control over the picture's colour palette.