The Picture Datatype
********************

   The V40 picture.datatype distributed with OS 3.1 had several weak
points and missing features which made it inadequate when the first RTG
systems with true-color support became available.  For this reason,
nowadays the original V40/V42 version has been obsoleted by third party
replacements featuring true-color support and other useful extensions.

   OS 3.5 integrates a rewritten picture.datatype whose API tries to be
as compatible as possible to these unofficial versions.

   The V44 picture.datatype works transparently with both `CyberGraphX'
and `Picasso 96'. It also integrates color reduction algorithms to
convert high/true-color pictures to palette-mapped bitmaps. The API
allows the programmer to choose among several quantization and
dithering techniques to get better quality or faster conversion.

General concepts
================

palette-mapped
     a picture, bitmap or screen is said to be palette-mapped when the
     color of its pixels must be determined by looking up a color
     palette containing the RGB triplets associated with an index
     value. The palette is also called CLUT (Color Look-Up Table).

direct-mapped
     a picture, bitmap or screen whose pixels directly contain an RGB
     triplet. Direct-mapped pictures do not need a palette.

native bitmap
     a bitmap in which the image data is represented by bitplanes in
     the native format of the Amiga chipset (OCS/ECS/AGA).

RTG bitmap
     a bitmap with a custom pixel format which may not be accessed
     directly. Drawing into the bitmap must be performed through the
     functions provided by the graphics.library or by the RTG system.

Backwards compatibility
=======================

   For backwards compatibility, the unofficial V43 picture.datatype
implementations which were distributed with `CyberGraphX' and `Picasso
96' behaved just like the V42 and eariler implementations by default.
The picture returned to the application was stored in a native planar
bitmap, up to 8 bitplanes deep.

   In order to let the datatype allocate custom bitmaps (chunky 8bpp or
hi/truecolor), the application should set the PDTA_DestMode attribute
to PMODE_V43.

   This has changed as of V44. PMODE_V43 is now active by default.
Applications should never expect to get a native bitmap from the
picture.datatype unless they explicitly ask for PMODE_V42.

   The following summary shows the different behaviour kept by all the
known implementations of the picture.datatype:

picture.datatype V40/V42 (OS 3.1)
     PDTA_DestMode is ignored.

picture.datatype V43 (CyberGraphX)
     PDTA_DestMode defaults to PMODE_V42. The returned bitmap is always
     a planar one, with up to 8 bitplanes.

picture.datatype V43 (Picasso 96)
     PDTA_DestMode defaults to PMODE_V42. However, the returned bitmap
     is NOT native.

picture.datatype V44 (OS 3.5)
     PDTA_DestMode defaults to PMODE_V43. It can be explicitly forced
     to PMODE_V42.

   The V42 mode is retained in picture.datatype V44 for backwards
compatibility only. Use of the V42 mode in new applications is STRONGLY
DISCOURAGED. The V43 mode provides better performance for both the
internal operations carried out by the datatype and for most bitmap to
screen blitting operations.

New methods in unofficial V43 picture.datatype
==============================================

PDTM_WRITEPIXELARRAY
     Transfer pixel data to the picture object in the specified format

PDTM_READPIXELARRAY
     Transfer pixel data from the picture object in the specified format

New tags in unofficial V43 picture.datatype
===========================================

PDTA_SourceMode
     Set the sub datatype interface mode

PDTA_DestMode
     Set the app datatype interface mode

PDTA_UseFriendBitMap
     Allocates the resulting bitmap as a friend bitmap

PDTA_MaskPlane
     NULL or mask plane for use with BltMaskBitMapRastPort()

New tags in V44
===============

PDTA_WhichPicture
     Index number of the picture to load

PDTA_GetNumPictures
     Get the number of pictures stored in the file

PDTA_MaxDitherPens
     Maximum number of colours to use for dithering

PDTA_DitherQuality
     Quality of the dithering algorithm to be used during color
     quantization

PDTA_AllocatedPens
     Pointer to the allocated pen table