picture.datatype

the root data type for pictures.

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

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)

PDTM_SCALE

Scale the pixel data to a new size. Scaling is only possible before the first GM_LAYOUT has been performed. (V45)

PDTM_OBTAINPIXELARRAY

Ask for access to the internal pixmap. This method can be used as a potentially faster alternative to PDTM_READPIXELARRAY and PDTM_WRITEPIXELARRAY. Requires that PDTA_DestMode==PMODE_V43 and/or PDTA_SourceMode==PMODE_V43, as described below. Returns TRUE on success, filling the struct pdtBlitPixelArray to describe the format of the internal pixel buffer, with pbpa_PixelData also being non-NULL. Be sure to use pbpa_PixelArrayMod to step through the rows. If pbpa_PixelData is NULL, or pbpa_PixelFormat does not match what you expect or need, you should revert to using PDTM_READPIXELARRAY or PDTM_WRITEPIXELARRAY.

In OM_NEW of a subclass, should not be used until after the SetDTAttrs() call where setting DTA_NominalHoriz, DTA_NominalVert and PDTA_SourceMode to PMODE_V43. (V47)

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.

NOTE WELL: earlier versions of this document used to describe PDTA_DestMode as defaulting to PMODE_V43, but actually it has defaulted to PMODE_V42 since version 45.10 (28.6.2001). The description does now reflect the real implementation.

Applicability is (ISG). Defaults to PMODE_V42. (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.

Note that if you set the mask bit plane picture.datatype may make a copy of it, assuming that it is the same width and height as given in the BitMapHeader bmh_Width/bmh_Height. The mask bit plane can only be set once and then only if no mask bit plane has been computed yet, e.g. for the transparent background colour.

Applicability is (SG). Defaults to NULL. (V43) Setting the mask bit plane requires picture.datatype V47 or higher.

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)

PDTA_ScaleQuality (ULONG)

Quality of the scaling algorithm to be used with PDTM_SCALE. A value of 0 means fast'n'ugly, while 1 means slow'n'nice.

Applicability is (ISG). Defaults to 0. (V45)

PDTA_ObtainPixelBuffer (APTR)

ask for permission to write directly into the backbuffer pixmap. Pass this request alongside PDTA_SourceMode=PMODE_V43, DTA_NominalHoriz, and DTA_NominalVert to SetDTAttrs(). The argument shall be a pointer to a zeroed struct pdtBlitPixelArray* If successful, pbpa_PixelData will be nonzero and the other parameters of that struct are set up for direct writing into pbpa_PixelData. 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

Applicability is (S)

PDTA_SubClassRendersAll (ULONG)

allow a dirty (non zeroed) frame buffer in V43 mode. This property can save a redundant memory clear operation for subclasses

1=yes, the subclass will write the whole frame buffer 0=clear buffer by picture.datatype upon allocation

Applicability is (S). Defaults to 0. (V43)

PDTA_AlphaChannel (BOOL)

returns TRUE if the bitmap has a valid Alpha channel. While subclasses should reflect mskHasAlpha in the bitmap header that could be checked by applications, this tag may also be used to verify whether the picture.datatype is Alpha aware.

Applicability is (ISG). Added in V47.9.

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.

Transparency support, including Alpha channel: Traditionally, transparent parts of the images were indicated by a binary decision based on a transparent color index, a dedicated mask plane or an implicit mask plane (lasso). Modern approaches allow for semi-transparent pixels by an opacity value in the Alpha channel. Since picture.datatype 47.10, it's internal rendering methods (GM_RENDER,DTM_DRAW) are transparency aware and will render accordingly. Applications with the intent of custom rendering by obtaining the bitmap from picture.datatype (after PROCLAYOUT) will need additional information. The pointer returned by PDTA_MaskPlane can be used in conjunction with the bitmap for BltMaskBitMapRastPort(). Please make sure that the Bitmap/Mask combination is suitable for the target screen (pass PDTA_Screen before or with DTM_PROCLAYOUT). Depending on the screen mode, picture.datatype may have decided to threshold an Alpha channel into a mask that can be used as outlined above. Applications with a desire to obtain the full 24 bit RGB plus Alpha information can do so by PDTM_READPIXELARRAY with PBPAFMT_RGBA or PBPAFMT_ARGB as 32 bit color format. Alpha availability in a given picture may be checked by PDTA_AlphaChannel.