Go to the first, previous, next, last section, table of contents.

# 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

Go to the first, previous, next, last section, table of contents.