Difference between revisions of "Picture Datatype"

From wiki.amiga.org
Jump to navigation Jump to search
 
(13 intermediate revisions by the same user not shown)
Line 1: Line 1:
TABLE OF CONTENTS
+
=Introduction=
 +
 +
The '''picture.datatype''' is the root datatype class for pictures. It is the super-class for any picture related classes.
  
picture.datatype<br>
+
=Version=
picture.datatype/PDTM_QUANTIZEPIXELARRAY<br>
 
picture.datatype/PDTM_SCALE<br>
 
picture.datatype/PDTM_SCALEPIXELARRAY<br>
 
picture_dtc/OM_DISPOSE<br>
 
picture_dtc/OM_GET<br>
 
picture_dtc/OM_NEW<br>
 
picture_dtc/OM_SET<br>
 
  
 +
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
  
picture.datatype
+
=Installation=
NAME
 
  picture.datatype -- the root datatype class for pictures.
 
 
 
FUNCTION
 
  The picture.datatype is the super-class for any picture related classes.
 
 
 
METHODS
 
  OM_NEW                -- Create and initialise a new picture object.
 
 
 
  OM_GET                -- Obtain the value of an attribute.
 
 
 
  OM_SET                -- Set the value(s) of multiple attributes.
 
 
 
  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
 
  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.
+
|[[File:Classes_Icon.png|center]]
 +
|Manual installation:
 +
Copy the file '''picture.datatype''' to '''SYS:Classes/Datatypes''' directory
  
      Applicability is (G)
+
|}
  
  PDTA_ColorRegisters                    (struct ColorRegister *)
+
&nbsp;
      The colour table of the source picture.  The contents of this
 
      table should match the corresponding entries in PDTA_CRegs.
 
  
      Applicability is (IG)
+
=Methods=
  
  PDTA_CRegs                              (uint32 *)
+
== Supported methods ==
      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)
+
{| class="wikitable"
 +
!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.
  
  PDTA_GRegs                              (uint32 *)
+
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.
      The colour table of the remapped picture, containing three
+
|-
      long word triplets per entry representing the RGB components of the
+
|PDTM_SCALEPIXELARRAY
      colour. See SetRGB32() and SetRGB32CM() for more information.
+
|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.
 +
|}
  
      Applicability is (G)
+
=Tags=
  
  PDTA_ColorTable                         (uint8 *)
+
{| class="wikitable"
      An array of pen values representing shared pens allocated during
+
!Tag ID
      the remapping process.
+
!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)
 +
|}
  
      Applicability is (G)
 
  
  PDTA_ColorTable2                        (uint8 *)
+
==Notes==
      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)
+
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).
 
 
  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-allocated
 
      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,
+
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.
  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
+
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.
  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
+
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):
  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
 
   -  the colour specified as BGCOLOR in env-var
 
   -  colour index 0 for transparent/lasso masking
 
   -  colour index 0 for transparent/lasso masking
Line 450: Line 322:
 
   -  #cccccc/rgb(204,204,204) if all else fails
 
   -  #cccccc/rgb(204,204,204) if all else fails
  
  The masking option of 'lasso' is supported with proviso: the fill occurs
+
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.
  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
  
  There is also the option of specifying certain default behaviour by use
+
These options are as follows:
  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,
 
   FORCEV43/S,REDMEAN/S,NOIPREFS/S,QUANT=QUANTIZATION/K/N,DITHER/K/N,
 
   SCALE/K/N,MAXPENS/K/N,BGCOLOR/K
 
   SCALE/K/N,MAXPENS/K/N,BGCOLOR/K
Line 476: Line 342:
 
                 hexadecimal notation '#RGB', or '#RRGGBB'
 
                 hexadecimal notation '#RGB', or '#RRGGBB'
  
  Using different values for DITHER and QUANT can produce significantly
+
Using different values for DITHER and QUANT can produce significantly different results, depending on your use case.
  different results, depending on your use case.
 
  
picture.datatype/PDTM_QUANTIZEPIXELARRAYture.datatype/PDTM_QUANTIZEPIXELARRAY
+
=picture.datatype/PDTM_QUANTIZEPIXELARRAY=
 
  NAME
 
  NAME
 
   PDTM_QUANTIZEPIXELARRAY  -- Analyse the specified rectangular pixel array
 
   PDTM_QUANTIZEPIXELARRAY  -- Analyse the specified rectangular pixel array
Line 547: Line 412:
  
  
picture.datatype/PDTM_SCALE                       picture.datatype/PDTM_SCALE
+
=picture.datatype/PDTM_SCALE=
 
  NAME
 
  NAME
 
   PDTM_SCALE      -- Scale the pixel data to a new size.
 
   PDTM_SCALE      -- Scale the pixel data to a new size.
Line 578: Line 443:
  
  
picture.datatype/PDTM_SCALEPIXELARRAY   picture.datatype/PDTM_SCALEPIXELARRAY
+
=picture.datatype/PDTM_SCALEPIXELARRAY=
 
  NAME
 
  NAME
 
   PDTM_SCALEPIXELARRAY  -- Scale the specified rectangular pixel array.
 
   PDTM_SCALEPIXELARRAY  -- Scale the specified rectangular pixel array.
Line 622: Line 487:
  
  
picture_dtc/OM_DISPOSE                                 picture_dtc/OM_DISPOSE
+
=picture_dtc/OM_DISPOSE=
 
  NAME
 
  NAME
     OM_DISPOSE -- Dispose an instance of a document class object.
+
     OM_DISPOSE -- Dispose an instance of a picture object.
  
 
  SYNOPSIS
 
  SYNOPSIS
Line 631: Line 496:
  
 
  FUNCTION
 
  FUNCTION
   Dispose of the specified document class object instance.
+
   Dispose of the specified picture object instance.
  
 
  INPUTS
 
  INPUTS
Line 645: Line 510:
  
  
picture_dtc/OM_GET                                         picture_dtc/OM_GET
+
=picture_dtc/OM_GET=
 
  NAME
 
  NAME
 
     OM_GET -- Get an attribute values for an object.
 
     OM_GET -- Get an attribute values for an object.
Line 668: Line 533:
  
  
picture_dtc/OM_NEW                                         picture_dtc/OM_NEW
+
=picture_dtc/OM_NEW=
 
  NAME
 
  NAME
     OM_NEW -- Initialise a new instance of a document class object.
+
     OM_NEW -- Initialise a new instance of a picture object.
  
 
  SYNOPSIS
 
  SYNOPSIS
Line 677: Line 542:
  
 
  FUNCTION
 
  FUNCTION
   Initialise a new instance of a document class object and apply the
+
   Initialise a new instance of a picture object and apply the
 
   attribute values specified.
 
   attribute values specified.
  
Line 692: Line 557:
  
  
picture_dtc/OM_SET                                         picture_dtc/OM_SET
+
=picture_dtc/OM_SET=
 
  NAME
 
  NAME
 
     OM_SET -- Set the values for attributes on the object.
 
     OM_SET -- Set the values for attributes on the object.

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

Classes Icon.png
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>