AmigaOS 3.2 DataTypes

AmigaOS 3.2 ships a complete set of datatype classes, all bumped to V47. The set includes classes that previously came only with OS 3.5/3.9 (gif, jpeg, aiff), new classes (png, icon, acbm) and rewrites (bmp). It also extends the root classes: picture.datatype gains direct pixel-buffer access and an alpha channel query, sound.datatype handles samples wider than 8 bits, and datatypes gains a new trigger method. This page collects what changed for developers, based on the NDK 3.2 R4 headers, class autodocs and release notes.

For the basics of opening, laying out and drawing a datatype object, see the DataTypes Tutorial.

Classes shipped with 3.2

Class Family / superclass Last 3.2 release (release notes) Notes
picture.datatype root of pictures 47.5 (22.5.2020); header pictureclass.h 47.4 V47 pixel buffer, writable mask, alpha
ilbm.datatype picture 47.4 (3.3.2021) Reads mask plane, FastRAM loading for RTG
acbm.datatype picture 47.1 (8.4.2020) New: "Created ACBM datatype based on ILBM datatype 47.1"
bmp.datatype picture 47.3 (28.9.2019) 47.1 is "almost a complete rewrite"
gif.datatype picture 47.2 (21.6.2020) Incorporated into 3.2, bumped to V47
jpeg.datatype picture 47.6 (21.6.2020) New libjpeg-turbo based decoder
png.datatype picture 47.3 (7.5.2020) New in 3.2; can also save PNG
icon.datatype picture 47.3 (11.06.2020) New: icons as pictures; MagicWB or ROMIcons palette for planar icons (compile-time choice)
sound.datatype root of sounds 47.6 (14.11.2020) SDTA_BitsPerSample
8svx.datatype sound 47.1 (12.3.2021) Stereo 8SVX (since 45.1)
aiff.datatype sound 47.2 (3.4.2021) ">8-bit playback/recording"
wav.datatype sound 47.2 (3.4.2021) "Ported to OS3.2"
animation.datatype root of animations 47.11 (11.nov.2020) Playback timing and buffering rework
anim.datatype animation 47.2 (11.04.2020) FPS from frame time
cdxl.datatype animation 47.6 (10.12.2020) Speed and stereo controls via ENV
text.datatype root of text 47.13 (4.3.2021) Search window, clipboard copy
ascii.datatype text 47.1 (15.3.2021)
amigaguide.datatype AmigaGuide documents 47.25 (3.4.2021) @{IMG}, forward history, wheel scrolling

The autodocs (Autodocs/*_dtc.doc) give the superclasses: 8svx and wav are "a sub-class of the sound.datatype", acbm, bmp and ilbm are subclasses of picture.datatype, ascii is a subclass of text.datatype, and cdxl is a subclass of animation.datatype. For gif, jpeg, png, icon and aiff, the family comes from their release notes, which describe them handing data to picture.datatype or as sound classes.

Testing which datatype handles a file

ObtainDataTypeA() examines a file and returns the matching struct DataType. Its dtn_Header gives the descriptor's name, base name and group:

#include <datatypes/datatypes.h>
#include <proto/datatypes.h>
#include <proto/dos.h>

void identify(CONST_STRPTR name)
{
    BPTR lock;
    struct DataType *dtn;

    if ((lock = Lock(name, ACCESS_READ)) != 0)
    {
        if ((dtn = ObtainDataType(DTST_FILE, (APTR)lock, TAG_DONE)) != NULL)
        {
            struct DataTypeHeader *dth = dtn->dtn_Header;

            Printf("%s: %s (base %s), group %s\n", name,
                   dth->dth_Name, dth->dth_BaseName,
                   dth->dth_GroupID == GID_PICTURE ? "picture" :
                   dth->dth_GroupID == GID_SOUND   ? "sound"   :
                   dth->dth_GroupID == GID_ANIMATION ? "animation" :
                   dth->dth_GroupID == GID_TEXT    ? "text" : "other");
            ReleaseDataType(dtn);
        }
        else
            PrintFault(IoErr(), name);   /* e.g. ERROR_OBJECT_NOT_FOUND */
        UnLock(lock);
    }
}

For DTST_FILE the handle is a BPTR lock. Since V44 you can also pass DTST_MEMORY with DTA_SourceAddress/DTA_SourceSize to examine data in memory, which subclasses then see as a file. Do not assume the "file" can be reopened. On failure, IoErr() returns ERROR_NO_FREE_STORE, ERROR_OBJECT_NOT_FOUND or ERROR_NOT_IMPLEMENTED (unknown handle type).

picture.datatype

Attribute and method map

All values are taken from datatypes/pictureclass.h 47.4:

Tag Value Type Since Applicability (autodoc)
PDTA_ModeID 3.1+ DTA_Dummy+200 ULONG ISG
PDTA_BitMapHeader 3.1+ +201 struct BitMapHeader * G
PDTA_BitMap 3.1+ +202 struct BitMap * ISG
PDTA_ColorRegisters 3.1+ +203 struct ColorRegister * G
PDTA_CRegs / PDTA_GRegs +204 / +205 ULONG * G
PDTA_ColorTable / PDTA_ColorTable2 +206 / +207 UBYTE * G
PDTA_Allocated 3.1+ +208 obsolete, do not use
PDTA_NumColors / PDTA_NumAlloc +209 / +210 UWORD ISG / G
PDTA_Remap 3.1+ +211 BOOL I, default TRUE
PDTA_Screen 3.1+ +212 struct Screen * IS
PDTA_FreeSourceBitMap 3.1+ +213 BOOL IS
PDTA_Grab 3.1+ +214 Point * ISG
PDTA_DestBitMap 3.1+ +215 struct BitMap * G
PDTA_ClassBitMap 3.1+ +216 struct BitMap * ISG
PDTA_NumSparse / PDTA_SparseTable +217 / +218 UWORD / UBYTE * I
PDTA_WhichPicture 3.5+ +219 ULONG V44 I
PDTA_GetNumPictures 3.5+ +220 ULONG * V44 I
PDTA_MaxDitherPens 3.5+ +221 ULONG V44 ISG, default 125
PDTA_DitherQuality 3.5+ +222 ULONG V44 ISG, default 1
PDTA_AllocatedPens 3.5+ +223 UBYTE * V44 G
PDTA_ScaleQuality 3.1.4+ +224 ULONG V45 ISG, 0 = fast, 1 = nice
PDTA_SourceMode 3.2+ +250 LONG V43 ISG, default PMODE_V42
PDTA_DestMode 3.2+ +251 LONG V43 ISG, default PMODE_V42
PDTA_UseFriendBitMap 3.2+ +255 BOOL V43 ISG, default TRUE
PDTA_AlphaChannel 3.2+ +256 BOOL 47.9 ISG
PDTA_MaskPlane 3.2+ +258 PLANEPTR V43 SG; setting requires V47
PDTA_ObtainPixelBuffer 3.2+ +260 struct pdtBlitPixelArray * V47 S
PDTA_SubClassRendersAll 3.2+ +261 LONG V47 S, default 0
Method Value Message Since
PDTM_WRITEPIXELARRAY 3.2+ PDTM_Dummy+0 (DTM_Dummy+0x60) struct pdtBlitPixelArray V43
PDTM_READPIXELARRAY 3.2+ PDTM_Dummy+1 struct pdtBlitPixelArray V43
PDTM_SCALE 3.2+ PDTM_Dummy+2 struct pdtScale V45
PDTM_OBTAINPIXELARRAY 3.2+ PDTM_Dummy+7 struct pdtObtainPixelArray V47

Pixel formats for pbpa_PixelFormat:

Constant Value Layout
PBPAFMT_RGB 3.2+ 0 3 bytes: R, G, B
PBPAFMT_RGBA 3.2+ 1 4 bytes: R, G, B, A
PBPAFMT_ARGB 3.2+ 2 4 bytes: A, R, G, B
PBPAFMT_LUT8 3.2+ 3 1 byte, separate colour map
PBPAFMT_GREY8 3.2+ 4 1 byte, 0 = black, 255 = white

BitMapHeader.bmh_Masking uses mskNone 0, mskHasMask 1, mskHasTransparentColor 2, mskLasso 3 and mskHasAlpha 4.

V42 vs. V43 interface modes

PDTA_SourceMode is for subclass writers. PMODE_V42 (0) means the subclass supplies a bitmap, and PMODE_V43 (1) means it sends PDTM_WRITEPIXELARRAY messages. PDTA_DestMode is for applications. With PMODE_V42 you only get standard (planar) bitmaps. With PMODE_V43 you "must not examine the contents of the BitMap you receive".

Gotcha: older documentation said PDTA_DestMode defaulted to PMODE_V43. It has actually defaulted to PMODE_V42 since 45.10. The env variable ENV:classes/datatypes/picture/ForceV43 holds "a list of all programs that should be forced to v43 mode". Since 46.12, the values yes/no are treated specially to work around older boolean settings.

Several 3.2 fixes concern legacy V42 mode. In 47.3, a truecolor layout in V42 mode no longer reports PDTA_NumColors as 1, and promoting a CLUT picture to truecolor no longer pushes bmh_Depth above 8 for V42 clients. The Classes/DataTypes/Picture/DitherHiColour variable is now read only when the target screen really is hicolor.

Direct pixel buffer access (V47)

A V43-mode subclass can now write straight into picture.datatype's back buffer instead of sending one PDTM_WRITEPIXELARRAY per line. Pass PDTA_ObtainPixelBuffer to SetDTAttrs() together with PDTA_SourceMode = PMODE_V43, DTA_NominalHoriz and DTA_NominalVert. Its argument is a zeroed struct pdtBlitPixelArray:

struct pdtBlitPixelArray pbpa;
memset(&pbpa, 0, sizeof(pbpa));

SetDTAttrs(obj, NULL, NULL,
           PDTA_SourceMode,        PMODE_V43,
           DTA_NominalHoriz,       width,
           DTA_NominalVert,        height,
           PDTA_ObtainPixelBuffer, &pbpa,
           TAG_DONE);

if (pbpa.pbpa_PixelData != NULL &&
    pbpa.pbpa_PixelFormat == PBPAFMT_RGB)
{
    /* write rows of pbpa.pbpa_PixelArrayMod bytes into pbpa_PixelData */
}
else
{
    /* fall back to DoSuperMethod(..., PDTM_WRITEPIXELARRAY, ...) */
}

The header rules: "If successful, pbpa_PixelData will be nonzero and the other parameters of that struct are set up for direct writing… In case that pbpa_PixelFormat is unsupported by the sub-datatype, then please revert to PDTM_WRITEPIXELARRAY. Please don't mix direct writes and PDTM_WRITEPIXELARRAY method invocations." jpeg.datatype 47.2 "implemented direct write into picture.datatype where available (V47)".

PDTA_SubClassRendersAll set to 1 means "the subclass will write the whole frame buffer", which saves picture.datatype from clearing the buffer first.

PDTM_OBTAINPIXELARRAY returns the internal buffer details through popa_PixelArray. Its popa_Flags accepts POPAF_WRITEGREY8: "If array is 8-bit, request it be set for PBPAFMT_GREY8 writes instead of LUT8". This ties in with the 47.5 change: "Now the internal map is of the type LUT8 for 8 bit inputs instead of GRAY8. It is necessary to write the color map in order to complete the input phase for 8 bit types successfully."

Grey data gotcha (autodoc): writing PBPAFMT_GREY8 through PDTM_WRITEPIXELARRAY resets the palette to 256 grey levels when the first line is written. Use PBPAFMT_LUT8 if you need control over the palette.

Mask plane and alpha channel

  • PDTA_MaskPlane is gettable for use with BltMaskBitMapRastPort(). Since 47.1 it is also settable, "for the benefit of ilbm.datatype". The mask can be set only once, and only if no mask has been computed yet (for example, for a transparent colour). picture.datatype may copy it, assuming bmh_Width × bmh_Height. ilbm.datatype 47.1 now reads the ILBM mask plane and passes it on this way.
  • PDTA_AlphaChannel (47.9) returns TRUE when the bitmap has a valid alpha channel. It also tells you whether the picture.datatype you are running is alpha-aware at all.
  • Since 47.10, GM_RENDER/DTM_DRAW are "transparency aware and will render accordingly". If you draw the bitmap yourself after DTM_PROCLAYOUT, use PDTA_MaskPlane. Pass PDTA_Screen before or with the layout, because depending on the screen mode the datatype "may have decided to threshold an Alpha channel into a mask".
  • To get full RGB plus alpha, use PDTM_READPIXELARRAY with PBPAFMT_RGBA or PBPAFMT_ARGB.

icon.datatype 47.3 sends "transparent color index and mode" to picture.datatype. Because of problems with MultiView, it replaces the transparent colour with the front screen's first colour.

Scaling

PDTM_SCALE (V45) takes ps_NewWidth, ps_NewHeight and ps_Flags (0 for now). "Scaling is only possible before the first GM_LAYOUT has been performed." Use PDTA_ScaleQuality to choose quality. Scaling fixes in 3.x:

  • 46.8: downscaling now works (earlier only upscaling worked).
  • 47.3: chunky-source pictures scale up to 65535× instead of 255×, and interpolated upscaling fills the last rows.
  • 47.3: upscaling a CHIP-memory planar bitmap vertically to a destination wider than 1008 pixels now uses a replacement routine, because BitMapScale() doesn't support "big blits". This is fixed on ECS/AGA but not on OCS.

Multi-picture files

Set PDTA_GetNumPictures to a ULONG pre-loaded with PDTANUMPICTURES_Unknown (0), and set PDTA_WhichPicture to 0. If the count comes back greater than 1, create a new object with PDTA_WhichPicture = n. An index that is out of range makes NewDTObject() fail with DTERROR_NOT_AVAILABLE (2009). Older subclasses ignore both tags. gif.datatype supports them (since 44.2).

sound.datatype

The 3.2 addition is SDTA_BitsPerSample (SDTA_Dummy+18, sound.datatype 47.1):

Tag Value Type Since Notes
SDTA_VoiceHeader 3.1+ SDTA_Dummy+1 struct VoiceHeader * Valid on get/set only since V44
SDTA_Sample 3.1+ +2 BYTE * Need not be CHIP (V40) or word-aligned (V44)
SDTA_SampleLength 3.1+ +3 ULONG Per channel, in bytes
SDTA_Period 3.1+ +4 UWORD Default 394, limited to ≥124
SDTA_Volume 3.1+ +5 UWORD 0..64
SDTA_Cycles 3.1+ +6 UWORD
SDTA_SignalTask 3.1+ +7 struct Task * V40
SDTA_SignalBit (= SDTA_SignalBitMask) +8 ULONG V40 Really a mask
SDTA_Continuous 3.1+ +9 BOOL V40
SDTA_SignalBitNumber 3.2+ +10 BYTE V44 -1 disables
SDTA_SamplesPerSec 3.2+ +11 UWORD V44 ≤ 28000 reliable
SDTA_ReplayPeriod 3.2+ +12 TimeVal_Type * V44 G
SDTA_LeftSample / SDTA_RightSample +13 / +14 BYTE * V44 Stereo
SDTA_Pan 3.2+ +15 BYTE V44 -64..64
SDTA_FreeSampleData 3.2+ +16 BOOL V44 Defaults to TRUE
SDTA_SyncSampleChange 3.2+ +17 BOOL V44
SDTA_BitsPerSample 3.2+ +18 UBYTE V47 8, 16, 24 or 32

Ordering gotcha: SDTA_BitsPerSample must be set before SDTA_SampleLength. Both autodoc entries say so. For 16/24/32-bit data the tag is mandatory "to get them (poorly) converted to 8-bit". The header comment lists "8, 16 or 32", while the autodoc lists 8, 16, 24 or 32.

Other 3.2 sound fixes: seamless streaming playback (47.2–47.4), mono sounds sent to both channels (47.3), corrupt saving of 16- and 32-bit samples fixed (47.5), and restarting after running dry (47.6). 8svx.datatype 47.1 "no longer returns an incorrect value for SDTA_SamplesPerSec", and 45.4 stopped setting the Fibonacci-delta flag when saving PCM data.

animation.datatype

animationclass.h (47.1) is unchanged in 3.2. Its V44 items remain ADTA_PreloadFrameCount (ADTA_Dummy+8, default 10), ADTA_LeftSample/ADTA_RightSample/ADTA_SamplesPerSec (aliases of the SDTA_ tags), and ADTM_LOADNEWFORMATFRAME/ADTM_UNLOADNEWFORMATFRAME (0x707/0x708). The 3.2 work is in playback behaviour:

  • 47.1 fixed playback at half the requested FPS. 47.4 fixed playback speed below 68030.
  • 47.5 hides the controls and pointer after 3 seconds without mouse movement.
  • 47.10 added micro-buffering for audio/video and lets it skip every second frame to keep sync.
  • 47.11 centres the video and makes STM_PAUSE work (space bar in MultiView). The env variable classes/datatypes/animation/windowtape puts the tape deck below the video in window mode.

Subclass environment variables:

Variable Class Meaning
classes/datatypes/animation/anim/fpslimit anim 47.2 Limit maximum FPS on slow machines
classes/datatypes/animation/anim/fps anim 47.2 Force FPS, overrides fpslimit
classes/datatypes/animation/cdxl/cdspeed cdxl 47.2 Speed in CD-ROM units 1–63 (x1 = 150 KB/s)
classes/datatypes/animation/cdxl/speed cdxl 47.2 Speed in KB/s, overrides cdspeed
classes/datatypes/animation/cdxl/stereo cdxl 47.2 Force stereo separation
classes/datatypes/animation/cdxl/fps cdxl 47.3 FPS 1–60. Default 12 since 47.6

text, ascii and amigaguide

  • text.datatype 47.1 has an interactive search window that stays open. It also gained copy to clipboard. 47.11 makes DTM_PRINT return the real error code instead of always "CANCEL". 47.12 removes only the damage it actually repaired, which fixes writes over window borders (bug #1218).
  • ascii.datatype 45.3 fixed CSI 27 m (reverse off).
  • amigaguide.datatype adds the @{IMG <path>} command (47.14/47.15; width and height come from the image), a Forward button, the fake assign guidedir: for links and images (47.17), lines of 4096 characters or more (47.21), and scroll wheel support (47.22). In 47.24, DTM_REMOVEDTOBJECT frees loaded pictures so they are remapped when re-added on another screen.

datatypes.library changes

datatypesclass.h 47.2 adds one trigger method:

Constant Value Meaning
STM_UNRETRACE 3.2+ 21 "the forward companion to back aka STM_RETRACE" (V47)

The public "functions in V45 or higher" block of SFD/datatypes_lib.sfd lists FindMethod(), FindTriggerMethod(), CopyDTMethods(), CopyDTTriggerMethods(), FreeDTMethods(), GetDTTriggerMethodDataFlags(), SaveDTObjectA() and StartDragSelect(). datatypes.doc also documents DoDTDomainA(), FindToolNodeA(), LaunchToolA() and LockDataType() as V45. These four have no entry in the NDK SFD or clib/datatypes_protos.h, so the standard stubs do not cover them. Two more V45 additions are the STM_HELP/STM_SEARCH/STM_SEARCH_NEXT/STM_SEARCH_PREV triggers (17–20) and DTA_Class (V45.3, DTA_Dummy+62), which "Use[s] this class when creating new objects using NewDTObjectA".

Picture subclass notes

  • ilbm.datatype: when CAMG is missing or unsound, 45.4 synthesises a mode from the picture size. 47.3 loads 1–8 planes including EHB, but not HAM, into FastRAM on RTG systems. 47.4 fixed memory trashing with a mask plane on 8-bit images in V42 mode.
  • bmp.datatype 47.1 supports compression, bitfields, 16–32 bit truecolor and 1–8 bit palette images.
  • jpeg.datatype 47.x handles YCCK/CMYK to RGB conversion. It uses an optimised iDCT on 68020+ and keeps greyscale images at 8 bits to save memory (47.4).
  • png.datatype 47.2 fixed saving pictures as PNG.

See Also

Sources: NDK 3.2 R4 Include_H/datatypes/{pictureclass,soundclass,animationclass,datatypes,datatypesclass}.h, Autodocs/{picture,sound,animation,text,8svx,acbm,amigaguide,ascii,bmp,cdxl,ilbm,wav}_dtc.doc, Autodocs/datatypes.doc, SFD/datatypes_lib.sfd, ReleaseNotes/{picture,ilbm,acbm,bmp,gif,jpeg,png,icon,sound,8svx,aiff,wav,animation,anim,cdxl,text,ascii,amigaguide}-dt-RelNotes Updated: 2026-11-13