![[Contents]](../images/toc_d.gif)
![[Index]](../images/index_d.gif)
![[Help]](../images/help_d.gif)
![[Retrace]](../images/retrace_d.gif)
![[Browse <]](../images/prev.gif)
![[Browse >]](../images/next.gif)
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.