Latest revision as of 09:51, 18 April 2024

Introduction

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

Version

There are two versions available:

V46.13 is part of the SystemV46 installation for the A600GS
V54.13 is part of the SystemV54 and Enhancer Software V2.3 installation

Installation

Manual installation:

Copy the file picture.datatype to SYS:Classes/Datatypes directory

Methods

Supported methods

Method ID	Description
OM_NEW	Create and initialise a new picture object.
OM_SET	Set the value(s) of multiple attributes.
OM_GET	Obtain the value of an attribute.
OM_UPDATE	Update the value(s) of multiple attributes.
OM_DISPOSE	Dispose of a picture object.
GM_LAYOUT	Layout (remap) the object and notify the application of the title and size.
GM_HITTEST	Determine if the object has been hit by the mouse.
GM_GOACTIVE	Tell the object to become active.
GM_HANDLEINPUT	Handle any input directed at the object.
GM_RENDER	Cause the graphics to render.
DTM_PROCLAYOUT	Layout (remap) the picture on the current application's process.
DTM_FRAMEBOX	Obtain the display environment that the picture requires for display purposes.
DTM_SELECT	Select a rectangular region of the picture.
DTM_CLEARSELECTED	Deselect the selected region of the picture.
DTM_COPY	Copy the selected area of the picture to the clipboard as ILBM format. If no area has been selected, the entire picture is copied.
DTM_PRINT	Print the selected area of the picture. If no area has been selected, the entire picture is printed.
DTM_WRITE	Write the selected area of the picture to a file as ILBM format. If no area has been selected, then the entire picture is written.
DTM_DRAW	Causes the picture to be drawn. Requires that the function ObtainDTDrawInfo() be called before this method to obtain a lock on the object and that ReleaseDTDrawInfo() be called after to release that lock.
PDTM_READPIXELARRAY	Transfer pixel data OUT of the picture. Requires that PDTA_DestMode is PMODE_V43, as described below.
PDTM_WRITEPIXELARRAY	Transfer pixel data INTO the picture. Requires that PDTA_SourceMode is PMODE_V43, as described below.
PDTM_SCALE	Scale the pixel data to a new size. Scaling is only possible before the first GM_LAYOUT (remap) has been performed.
PDTM_OBTAINPIXELARRAY	Obtain a description of the internal pixel data buffer in order to allow direct access. MAY be used as an alternative to PDTM_READPIXELARRAY and PDTM_WRITEPIXELARRAY. Requires that PDTA_DestMode is PMODE_V43 as described below. Returns non-zero on success, filling the specified pdtBlitPixelArray structure with the format of the internal buffer, with pbpa_PixelData also being non-NULL. Ensure that pbpa_PixelArrayMod is honoured when stepping through rows. If pbpa_PixelData is NULL, of pbpa_PixelFormat does not match your requirements, use PDTM_READPIXELARRAY or PDTM_WRITEPIXELARRAY. In OM_NEW of subclasses, this method SHOULD NOT be called until after DTA_NominalHoriz / DTA_NominalVert have been specified and PDTA_SourceMode have been set to PMODE_V43.
PDTM_SCALEPIXELARRAY	Combines the PDTM_READPIXELARRAY and PDTM_SCALE methods to facilitate the reading of a scaled region of the picture without requiring the remapping process. Requires that PDTA_DestMode is PMODE_V43.
PDTM_QUANTIZEPIXELARRAY	Quantize the source palette into a smaller set of colours using a specified algoritm for the purposes of remapping. Requires that PDTA_DestMode is PMODE_V43.

Tags

Tag ID	Type	Description
OBP_Precision	(uint32)	The precision to use when obtaining pens during remapping. See the PRECISION_#? defines in <graphics/view.h> Defaults to PRECISION_IMAGE. Applicability is (I)
PDTA_ModeID	(uint32)	Get and set the id of the graphics mode for the picture. See <graphics/modeid.h> for more information. Defaults to 0. Applicability is (ISG)
PDTA_BitMapHeader	(struct BitMapHeader *)	Gets the basic dimensions of the picture. The BitMapHeader structure is defined in <datatypes/pictureclass.h>. Applicability is (G)
PDTA_SourceMode	(int32)	Used by subclass authors, this tag determines whether the picture object expects a BitMap as the input parameter (PMODE_V42) or MAY accept PDTA_WRITEPIXELARRAY messages or PDTM_OBTAINPIXELARRAY access instead (PMODE_V43). Defaults to PMODE_V42. Applicability is (ISG)
PDTA_DestMode	(int32)	Used by application authors, this tag determines whether the picture object will return only a standard format BitMap (PMODE_V42) up to 8-bit planar, or whether it will return a BitMap about whose memory layout the caller must not speculate or assume. If set to PMODE_V43, you SHOULD NOT examine or assume anything about the contents of the resulting BitMap. Defaults to PMODE_V42. Applicability is (ISG)
PDTA_BitMap	(struct BitMap *)	The pointer to the source bitmap. If PDTA_SourceMode = PMODE_V42, setting this BitMap will result in it being freed in OM_DISPOSE and may ONLY be up to 8-bit per pixel (planar). If PDTA_SourceMode = PMODE_V43, the BitMap is COPIED into the internal pixel buffer and MAY be any supported bit-depth. The caller is responsible for freeing the BitMap it provides. Where PDTA_SourceMode is PMODE_V43 and the pixel data has been written to the internal buffer, the result of OM_GET for this attribute will be a direct BitMap representation of the pixel buffer. Applicability is (ISG)
PDTA_ClassBitMap	(struct BitMap *)	A pointer to a source BitMap allocated by a subclass (for example,the ilbm.datatype) which imported the picture. The picture.dataype will never free this BitMap and the subclass is responsible for doing so. Applicability is (ISG)
PDTA_DestBitMap	(struct BitMap *)	A pointer to the remapped BitMap after the layout / remap process has occurred. Applicability is (G)
PDTA_ColorRegisters	(struct ColorRegister *)	The colour table of the source picture. The contents of this table should match the corresponding entries in PDTA_CRegs. Applicability is (IG)
PDTA_CRegs	(uint32 *)	The colour table of the source picture, containing three long word triplets per entry representing the RGB components of the colour. See SetRGB32() and SetRGB32CM() for more information. Applicability is (IG)
PDTA_GRegs	(uint32 *)	The colour table of the remapped picture, containing three long word triplets per entry representing the RGB components of the colour. See SetRGB32() and SetRGB32CM() for more information. Applicability is (G)
PDTA_ColorTable	(uint8 *)	An array of pen values representing shared pens allocated during the remapping process. Applicability is (G)
PDTA_ColorTable2	(uint8 *)	An array of pen values representing shared pens allocated during the remapping process. For most use cases, this table will contain the same values as PDTA_ColoraTable, but in other cases some of the colours in this table MAY match the original colour palette better. The picture.datatype uses the two tables during remapping, alternating for each pixel. Applicability is (G)
PDTA_AllocatedPens	(uint8 *)	An array of pens allocated during the remapping process. Each entry represents a pen allocated for a colour in the remapped colour palette. You may receive a NULL pointer as result where PDTA_Allocated or PDTA_NumAlloc is 0 (zero). Note that older documentation states that the entry corresponds to the same indexed entry in the remapped colour palette, which isn't strictly true (see NOTES below). Applicability is (G)
PDTA_Allocated	(uint32)	Gets the number of pens allocated and present within the associated PDTA_AllocatedPens array. This will typically be the same as the value of PDTA_NumAlloc but will be zero (0) where no pens were allocated on a screen. In this context, 'allocated' refers to the colours allocated via graphics.library/ObtainBestPen(). Applicability is (G)
PDTA_NumColors	(uint32)	The number of colours in the palette (PDTA_CRegs) for the source picture or PDTA_BitMap. Applicability is (ISG)
PDTA_NumAlloc	(uint32)	The number of colours allocated to the palette (PDTA_GRegs) for the remapped BitMap (PDTA_DestBitMap). Applicability is (G)
PDTA_Remap	(BOOL)	Indicates whether the picture should be remapped or not during the layout process. When not remapped, the bitmap (PDTA_DestBitMap) produces will be (almost) identical to the source BitMap. Defaults to TRUE. Applicability is (I)
PDTA_Screen	(struct Screen *)	A pointer to a Screen structure representing the screen to remap the picture to. Only used if the picture object is not added to a Window; primarily used when calling DTM_OBTAINDRAWINFO in order to remap the picture. Defaults to NULL. Applicability is (IS)
PDTA_FreeSourceBitMap	(BOOL)	Indicates whether the source bitmap should be freed immediately after the layout (remapping) method has finished. When PDTA_SourceMode = PMODE_V42, this will free the BitMap specified in PDTA_BitMap; for PDTA_SourceMode = PMODE_V43, this will free the internal BitMap representing the pixel buffer. Defaults to FALSE. Applicability is (ISG)
PDTA_Grab	(Point *)	A pointer to a Point structure that specifies the grab point of the picture. Defaults to (0,0) Applicability is (ISG)
PDTA_SparseTable	(uint8 *)	An array of pen numbers indicating which colours should be used when remapping the picture. This array MUST contain at least as many entries as indicated by PDTA_NumSparse. These are the pre-allocate pens to be used as a replacement to quantization; the remapped colour registers in PDTA_GRegs will be populated with the pen RGB colours. Defaults to NULL. Applicability is (I).
PDTA_NumSparse	(uint16)	The number of pens in the sparse colour table PDTA_SparseTable. Defaults to 0. Applicability is (I)
PDTA_UseFriendBitMap	(BOOL)	If set to TRUE, any BitMap allocations will be performed using a 'friend' BitMap, typically from the Screen to which the picture is being remapped. See graphics.library/AllocBitMap(). Defaults to TRUE. Applicability is (ISG)
PDTA_AlphaChannel	(BOOL)	Analogous to mskHasAlpha in the bmh_Masking field of the BitMapHeader. Is set to TRUE, indicates that the source picture has an alpha channel. Defaults to FALSE. Applicability is (IG)
PDTA_MaskPlane	(PLANEPTR)	A pointer to a bitplane suitable for use with a call to the function graphics.library/BltMaskBitMapRastPort() or NULL if the picture has no transparent colours. Defaults to NULL. Applicability is (G)
PDTA_PromoteMask	(BOOL)	If a colour-mapped (up to 8-bit) picture with a transparent colour needs to be "promoted" to a true-colour format, setting this to TRUE allows the PDTA_MaskPlane to be converted and carried over into the alpha channel of the destination BitMap. Defaults to FALSE. Applicability is (ISG)
PDTA_WhichPicture	(uint32)	Used by subclasses, specifies the index of the picture to load. For file that store more than one picture, the index number 0 would refer to the first picture, 1 to the second and so on. This tag is intended to work in conjunction with PDTA_GetNumPictures. To load a specific picture from a file, first check how many pictures are available from an initial picture object before constructing a second object to retrieve the desired picture. Old picture.datatype subclasses might not support the PDTA_WhichPicture and PDTA_GetNumPictures tags. The best way to determine if a subclass supports these tags is to query the value of PDTA_GetNumPictures; if supported, the subclass will modify this value. Old picture classes might also not support the PDTA_WhichPicture tag and always return the first picture, regardless of that requested. If the requested picture is not available (for example, you ask for picture #10 but there are only 3 pictures stored) the subclass SHOULD return NULL and set the error code DTERROR_NOT_AVAILABLE. This does not mean the file was not found, just that the picture with the requested index is not available. Defaults to 0. Applicability is (I)
PDTA_GetNumPictures	(uint32)	Query the number of pictures stored within the file. NOTE that old subclasses will ignore this tag. Subsequently the value supplied may not be modified, therefore you should initialise it to the constant value PDTANUMPICTURES_Unknown. This tag is unusual in that it does not operate on an already existing object in the GetDTAttrs() context. This was allegedly done for practical reasons: where the picture subclasss is still processing the image data, it MAY be more convenient to count the number of pictures in the file first that after the file was already read. Defaults to NULL. Applicability is (I)
PDTA_MaxDitherPens	(uint32)	The maximum number of pens to use during colour quantization. NOTE that some quantization algorithms require a power of two for optimal results. Defaults to 125. Applicability is (ISG)
PDTA_DitherQuality	(uint32)	Specifies the quality of the dithering algorithm to be used during colour quantization. A value of 0 (zero) yields little or no visible quality improvements which a value of 2 will yield noticeably better results. Generally, the higher the value requested, the better the output. The current version of the picture.datatype from AmigaKit Ltd can perform no dither (0), an error diffused dither (1), Bayer's ordered dither (2) and Burke's dither (a variant of Floyd-Steinberg, 3). Defaults to 1. Applicability is (ISG)
PDTA_ScaleQuality	(uint32)	Specifies the quality of the scaling algorithm to be used with the PDTM_SCALE method. A value of 0 (zero) means fast'n'ugly while 1 (one) means slow'n'nice. The results, however, may be subjective. Defaults to 0. Applicability is (ISG)
PDTA_ObtainPixelBuffer	(struct pdtBlitPixelArray *)	Provided for OS 3.2 compatibility and is the equivalent of the PDTM_OBTAINPIXELARRAY method. Applicability is (S)

Notes

Contrary to previous versions of the picture.datatype, the PDTA_Allocated tag now returns the number of pens allocated during layout or remap. For the common use of the picture class, this value will be the same as that for PDTA_NumAlloc but where layout/remap has been performed without a screen, no pens can be allocated even though the (number of) colours in the destination bitmap may have been altered. Making a distinction between these two facets of the datatype allow remapping to be performed without intending to display the result; for example, simply reducing the colours or scaling a picture does not require a screen yet prior implementations require that it does. Anecdotally, I do not believe PDTA_AllocatedPens works as described in the "official" documentation since PDTA_ColorTable and PDTA_ColorTable2 are described as having potentially different pens; so when this occurs, the documented nature of a 1:1 mapping of PDTA_GRegs to PDTA_AllocatedPens is evidently false because there are two potential pens for one colour map entry with no way to distinguish those in the PDTA_AllocatedPens series. If the number of colours for a colour-mapped picture is limited to 256 (8-bit) then PDTA_NumAlloc can never be higher than this, leading to the values in PDTA_AllocatedPens only list half of the actual pens allocated. Plus, the values of PDTA_AllocatedPens do not match the palette entry when this occurs. Therefore, PDTA_NumColors is to PDTA_CRegs as PDTA_NumAlloc is to PDTA_GRegs. Thus, PDTA_Allocated shares this same relationship to PDTA_AllocatedPens since PDTA_NumAlloc may differ from PDTA_Allocated (where one is the reduced palette and the other is the number of pens allocated for display).

The picture.datatype from AmigaKit Ltd, as with many of its predecessors, does not suffer from the layout restrictions present in the old revisions.That is, for example, an extra-halfbrite or HAM picture no longer requires you to open a custom screen for display - any screen will do.

Writing greyscale data to a picture (using PBPAFMT_GREY8 pixel format and PDTM_WRITEPIXELARRAY) automagically 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 wish this to happen, do not use PBPAFMT_GREY8 but instead use PBPAFMT_LUT8, which allows you to retain control over the picture colour palette.

Reading PBPAFMT_LUT8/GREY8 data from an underlying RGB pixel buffer will give a pseudo pen index using the RGB332 form (3 bits red, 3 bits green, 2 bits blue) into a palette of up to 256 colours. Reading the same from ARGB/RGBA pixels MAY induce colour blending with the designated background colour. Background colour defaults to (in order if priority):

  -  the colour specified as BGCOLOR in env-var
  -  colour index 0 for transparent/lasso masking
  -  BACKGROUNDPEN from any screen DrawInfo available
  -  #cccccc/rgb(204,204,204) if all else fails

The masking option of 'lasso' is supported with proviso: the fill occurs from (0,0). This means if the pixel at (0,0) is the transparent colour then effectively no fill will occur. This may or may not change in a future release of the datatype.

There is also the option of specifying certain default behaviour by use of the environmental variable "Datatypes/picture.datatype". Such options are the default state and will persist unless/until overridden by explicit setters by subclasses or callers

These options are as follows:

  FORCEV43/S,REDMEAN/S,NOIPREFS/S,QUANT=QUANTIZATION/K/N,DITHER/K/N,
  SCALE/K/N,MAXPENS/K/N,BGCOLOR/K
 Where,
  - FORCEV43    will force V43 source mode by default
  - REDMEAN     uses a better but more intensive colour comparison;
                the default is simple Euclidian distance.
  - NOIPREFS    do not attempt to account for IPrefs odd behaviour
  - QUANT       [0..3] specifies the default quantization algorithm
  - DITHER      [0..3] specifies the preferred dither algorithm
  - SCALE       [0..1] specifies the preferred scaling quality
  - MAXPENS     [2..256] overrides the max. pens when dithering
  - BGCOLOR     specifies a background colour to use when converting
                ARGB/RGBA to RGB or CLUT images; should be in the
                hexadecimal notation '#RGB', or '#RRGGBB'

Using different values for DITHER and QUANT can produce significantly different results, depending on your use case.

picture.datatype/PDTM_QUANTIZEPIXELARRAY

NAME
 PDTM_QUANTIZEPIXELARRAY  -- Analyse the specified rectangular pixel array
                             and generate a reduced colour palette for the
                             picture region.

FUNCTION
 Analyse the picture pixel buffer to determine an appropriate gamut for
 a reduced colour palette, using a choice of algorithms.  Some quantization
 methods produce better results than others.

INPUTS
   struct pdtQuantizePixelArray
      MethodID           - PDTM_SCALEPIXELARRAY
      pqpa_Which         - Specifies which algorithm to use (see below)
      pqpa_Left          - The left-most pixel to start analysing from
      pqpa_Top           - The top-most pixel to start analysing from
      pqpa_Width         - The width of the rectangle to analyse
      pqpa_Height        - The height of the rectangle to analyse
      pqpa_ColorRegs     - A pointer to the 32-bit RGB colour table
      pqpa_Length        - The required number of colours to find
      pqpa_Attrs         - Any other attributes.

   Quantization algorithms:
     The default quantization method for the picture datatype is controlled
     by the environment variable Datatypes/picture.datatype/QUANTIZATION
     with a value of "0" (popular), "1" (octree) or "2" (median cut).

     PQUANTIZE_POPULAR scans the pixels and returns a palette of the most
      frequently used N colours; can cause some aliasing where a lesser
      used colour has been omitted from the palette.

     PQUANTIZE_OCTREE scans the colours and provides an averaged (merged)
      colour for similar, lesser used colours; resulting in an adaptive
      colour palette for the remapped picture.

     PQUANTIZE_MEDIANCUT divides the pixels into buckets and sorts those
      buckets based on pixels with the greatest range before once
      more splitting the bucket(s);  resulting in an adaptive palette
      for the remapped picture.

     PQUANTIZE_PENS is a convenience function to producing the 32-bit RGB
      triplet table from a pen array, similar to GetRGB32().

     PQUANTIZE_VGA does not, in fact, quantize the pixel array but instead
      populates the colour table with the more common of the VGA
      colour palette(s), dependent on the number of colours.

RESULT
  Returns zero (0) if unsuccessful, otherwise a non-zero value when
  the scaling has completed.

NOTE
   This function does not perform remapping of colours and/or pens and as
   such does not imply a layout.  The resulting palette will likely contain
   colours not used in the original image as colours will have been combined
   to produce a "better match", particularly in the octree algorithm where
   similar but lesser used colours are combined to reduce the palette.

   The median cut algorithm requires that the number of requested colours be
   a power of 2 (e.g, 32, 64, 128) as the algorithm works by dividing the
   plane in half before analyzing colour ranges and continues until the
   number of colours has been reached.

   This function is bespoke to the AmigaKit Ltd picture.datatype replacement
   and is not (currently) present on the AmigaOS "official" picture class.

picture.datatype/PDTM_SCALE

NAME
 PDTM_SCALE       -- Scale the pixel data to a new size.

FUNCTION
   Resize the entire picture pixel array to the new dimensions, using
   either simple matrix, low-pass or bilinear scaling.

INPUTS
   struct pdtScale
      MethodID           - PDTM_SCALE
      ps_NewWidth        - The width of the destination pixel array
      ps_NewHeight       - The height of the destination pixel array
      ps_Flags           - Bitwise flags; see below.

   Flags currently include:
      PSCALE_FAST     (0)  - Use simple "matrix" based transformation
      PSCALE_BILINEAR (1)  - Use bilinear scaling or low-pass smoothing
      PSCALE_BICUBIC  (2)  - not yet supported

RESULT
  Returns zero (0) if unsuccessful, otherwise a non-zero value when
  the scaling has completed.

NOTES
  Scaling is only possible before the first GM_LAYOUT (remap) has been
  performed.  This operation modifies the internal pixel buffer to
  conform to the specified width and height, effectively destroying
  the original image: it cannot be undone.

picture.datatype/PDTM_SCALEPIXELARRAY

NAME
 PDTM_SCALEPIXELARRAY  -- Scale the specified rectangular pixel array.

FUNCTION
   Resize the rectangular region of the picture pixel array to the new
   dimensions, using either simple matrix, low-pass or bilinear scaling.
   Unlike the associated PDTM_SCALE method, the scaling of the pixel
   array does NOT require a layout and does not affect the destination
   bitmap since no remapping is done.

INPUTS
   struct pdtScalePixelArray
      MethodID           - PDTM_SCALEPIXELARRAY
      pspa_PixelData     - The buffer to receive the scaled pixel array
      pspa_PixelFormat   - The destination pixel array format
      pspa_PixelArrayMod - The number of octets per row
      pspa_Left          - The left-most pixel to scale from
      pspa_Top           - The top-most pixel to scale from
      pspa_Width         - The width of the rectangle to scale
      pspa_Height        - The height of the rectangle to scale
      pspa_NewWidth      - The width of the destination pixel array
      pspa_NewHeight     - The height of the destination pixel array
      pspa_Flags         - Bitwise flags; see below.

   Flags currently include:
      scaleFast     (0)  - Use simple "matrix" based transformation
      scaleBilinear (1)  - Use bilinear scaling or low-pass smoothing

RESULT
  Returns zero (0) if unsuccessful, otherwise a non-zero value when
  the scaling has completed.

NOTE
   This function does not perform remapping of colours and/or pens and as
   such does not imply a layout; the resulting scaled pixel array will be
   written to the supplied pixel buffer specified in the message.  It is
   possible using xRGB pixel buffers that some colours may differ from the
   original due to smoothing.

   This function is bespoke to the AmigaKit Ltd picture.datatype replacement
   and is not (currently) present on the AmigaOS "official" picture class.

picture_dtc/OM_DISPOSE

NAME
   OM_DISPOSE -- Dispose an instance of a picture object.

SYNOPSIS
   result = OM_DISPOSE(class, obj, msg)
   uint32 OM_DISPOSE(Class *, Object *, Msg)

FUNCTION
  Dispose of the specified picture object instance.

INPUTS
   class      - The Class pointer
   obj        - The Object instance.
   msg        - The dispose operation message.

RESULT
  Zero.

SEE ALSO
  picture_dtc/OM_NEW

picture_dtc/OM_GET

NAME
   OM_GET -- Get an attribute values for an object.

SYNOPSIS
   result = OM_GET(class, obj, msg)
   uint32 OM_GET(Class *, Object *, struct opGet *)

FUNCTION
  Retrieve an attribute value from the specified class instance.

INPUTS
   class      - The Class pointer
   obj        - The Object instance pointer
   msg        - The get operation message.

RESULT
   One (1L) if the attribute was found, otherwise zero (0L)

SEE ALSO
  markdown_dtc/OM_SET, <datatypes/pictureclass.h>

picture_dtc/OM_NEW

NAME
   OM_NEW -- Initialise a new instance of a picture object.

SYNOPSIS
   result = OM_NEW(class, obj, msg)
   uint32 OM_NEW(Class *, Object *, struct opSet *)

FUNCTION
  Initialise a new instance of a picture object and apply the
  attribute values specified.

INPUTS
   class      - The Class pointer
   obj        - The "true" Class pointer
   msg        - The set operation message.

RESULT
   A pointer to the object instance, or NULL on failure.

SEE ALSO
  picture_dtc/OM_DISPOSE

picture_dtc/OM_SET

NAME
   OM_SET -- Set the values for attributes on the object.

SYNOPSIS
   result = OM_SET(class, obj, msg)
   uint32 OM_SET(Class *, Object *, struct opSet *)

FUNCTION
  Attempt to set values for attributes on the object.

INPUTS
   class      - The Class pointer
   obj        - The Object instance pointer
   msg        - The set operation message.

RESULT
   One (1L) if the object needs a visual referesh to reflect the changes,
  otherwise zero (0L)

SEE ALSO
  root_cl/OM_GET, <datatypes/pictureclass.h>

Difference between revisions of "Picture Datatype"