Difference between revisions of "Picture Datatype"

From wiki.amiga.org
Jump to navigation Jump to search
Line 105: Line 105:
  
 
=TAGS=
 
=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.
+
{| class="wikitable"
      Applicability is (I)
+
!Tag ID
 
+
!
  PDTA_ModeID                            (uint32)
+
!Description
      Get and set the id of the graphics mode for the picture.
+
|-
      See <graphics/modeid.h> for more information.
+
|OBP_Precision
 
+
|(uint32)
      Defaults to 0.
+
|The precision to use when obtaining pens during remapping.
      Applicability is (ISG)
+
See the PRECISION_#? defines in <graphics/view.h>
 
+
Defaults to PRECISION_IMAGE.
  PDTA_BitMapHeader                       (struct BitMapHeader *)
+
Applicability is (I)
      Gets the basic dimensions of the picture.  The BitMapHeader structure
+
|-
      is defined in <datatypes/pictureclass.h>.
+
|PDTA_ModeID
 
+
|(uint32)
      Applicability is (G)
+
|Get and set the id of the graphics mode for the picture.
 
+
See <graphics/modeid.h> for more information.
  PDTA_SourceMode                         (int32)
+
Defaults to 0.
      Used by subclass authors, this tag determines whether the picture
+
Applicability is (ISG)
      object expects a BitMap as the input parameter (PMODE_V42) or MAY
+
|-
      accept PDTA_WRITEPIXELARRAY messages or PDTM_OBTAINPIXELARRAY access
+
|PDTA_BitMapHeader
      instead (PMODE_V43).
+
|(struct BitMapHeader *)
 
+
|Gets the basic dimensions of the picture.  The BitMapHeader structure is defined in <datatypes/pictureclass.h>.
      Defaults to PMODE_V42.
+
Applicability is (G)
      Applicability is (ISG)
+
|-
 
+
|PDTA_SourceMode
  PDTA_DestMode                           (int32)
+
|(int32)
      Used by application authors, this tag determines whether the picture
+
|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).
      object will return only a standard format BitMap (PMODE_V42) up to
+
Defaults to PMODE_V42.
      8-bit planar, or whether it will return a BitMap about whose memory
+
Applicability is (ISG)
      layout the caller must not speculate or assume.
+
|-
 
+
|PDTA_DestMode
      If set to PMODE_V43, you SHOULD NOT examine or assume anything about
+
|(int32)
      the contents of the resulting BitMap.
+
|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.
+
Defaults to PMODE_V42.
 
+
Applicability is (ISG)
      Applicability is (ISG)
+
|-
 
+
|PDTA_BitMap
  PDTA_BitMap                             (struct BitMap *)
+
|(struct BitMap *)
      The pointer to the source bitmap.  If PDTA_SourceMode = PMODE_V42,
+
|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.
      setting this BitMap will result in it being freed in OM_DISPOSE
+
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.
      and may ONLY be up to 8-bit per pixel (planar).
+
Applicability is (ISG)
      If PDTA_SourceMode = PMODE_V43, the BitMap is COPIED into the
+
|-
      internal pixel buffer and MAY be any supported bit-depth.  The
+
|PDTA_ClassBitMap
      caller is responsible for freeing the BitMap it provides.
+
|(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.
      Where PDTA_SourceMode is PMODE_V43 and the pixel data has been
+
Applicability is (ISG)
      written to the internal buffer, the result of OM_GET for this
+
|-
      attribute will be a direct BitMap representation of the pixel
+
|PDTA_DestBitMap
      buffer.
+
|(struct BitMap *)
 
+
|A pointer to the remapped BitMap after the layout / remap process has occurred.
      Applicability is (ISG)
+
Applicability is (G)
 
+
|-
  PDTA_ClassBitMap                       (struct BitMap *)
+
|PDTA_ColorRegisters
      A pointer to a source BitMap allocated by a subclass (for example,
+
|(struct ColorRegister *)
      the ilbm.datatype) which imported the picture.  The picture.dataype
+
|The colour table of the source picture.  The contents of this table should match the corresponding entries in PDTA_CRegs.
      will never free this BitMap and the subclass is responsible for
+
Applicability is (IG)
      doing so.
+
|-
 
+
|PDTA_CRegs
      Applicability is (ISG)
+
|(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.
  PDTA_DestBitMap                         (struct BitMap *)
+
Applicability is (IG)
      A pointer to the remapped BitMap after the layout / remap process
+
|-
      has occurred.
+
|PDTA_GRegs
 
+
|(uint32 *)
      Applicability is (G)
+
|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_ColorRegisters                     (struct ColorRegister *)
+
|-
      The colour table of the source picture.  The contents of this
+
|PDTA_ColorTable
      table should match the corresponding entries in PDTA_CRegs.
+
|(uint8 *)
 
+
|An array of pen values representing shared pens allocated during the remapping process.
      Applicability is (IG)
+
Applicability is (G)
 
+
|-
  PDTA_CRegs                             (uint32 *)
+
|PDTA_ColorTable2
      The colour table of the source picture, containing three
+
|(uint8 *)
      long word triplets per entry representing the RGB components of the
+
|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.
      colour.  See SetRGB32() and SetRGB32CM() for more information.
+
Applicability is (G)
 
+
|-
      Applicability is (IG)
+
|PDTA_AllocatedPens
 
+
|(uint8 *)
  PDTA_GRegs                             (uint32 *)
+
|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).
      The colour table of the remapped picture, containing three
+
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).
      long word triplets per entry representing the RGB components of the
+
Applicability is (G)
      colour.  See SetRGB32() and SetRGB32CM() for more information.
+
|-
 
+
|PDTA_Allocated
      Applicability is (G)
+
|(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().
  PDTA_ColorTable                         (uint8 *)
+
Applicability is (G)
      An array of pen values representing shared pens allocated during
+
|-
      the remapping process.
+
|PDTA_NumColors
 
+
|(uint32)
      Applicability is (G)
+
|The number of colours in the palette (PDTA_CRegs) for the source picture or PDTA_BitMap.
 
+
Applicability is (ISG)
  PDTA_ColorTable2                       (uint8 *)
+
|-
      An array of pen values representing shared pens allocated during
+
|PDTA_NumAlloc
      the remapping process.  For most use cases, this table will contain
+
|(uint32)
      the same values as PDTA_ColoraTable, but in other cases some of the
+
|The number of colours allocated to the palette (PDTA_GRegs) for the remapped BitMap (PDTA_DestBitMap).
      colours in this table MAY match the original colour palette better.
+
Applicability is (G)
      The picture.datatype uses the two tables during remapping, alternating
+
|-
      for each pixel.
+
|PDTA_Remap
 
+
|(BOOL)
      Applicability is (G)
+
|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.
  PDTA_AllocatedPens                     (uint8 *)
+
Applicability is (I)
      An array of pens allocated during the remapping process.  Each entry
+
|-
      represents a pen allocated for a colour in the remapped colour palette.
+
|PDTA_Screen
      You may receive a NULL pointer as result where PDTA_Allocated or
+
|(struct Screen *)
      PDTA_NumAlloc is 0 (zero).
+
|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.
      Note that older documentation states that the entry corresponds to the
+
Applicability is (IS)
      same indexed entry in the remapped colour palette, which isn't strictly
+
|-
      true (see NOTES below).
+
|PDTA_FreeSourceBitMap
 
+
|(BOOL)
      Applicability is (G)
+
|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.
  PDTA_Allocated                         (uint32)
+
Applicability is (ISG)
      Gets the number of pens allocated and present within the associated
+
|-
      PDTA_AllocatedPens array.  This will typically be the same as the
+
|PDTA_Grab
      value of PDTA_NumAlloc but will be zero (0) where no pens were
+
|(Point *)
      allocated on a screen.  In this context, 'allocated' refers to the
+
|A pointer to a Point structure that specifies the grab point of the picture.
      colours allocated via graphics.library/ObtainBestPen().
+
Defaults to (0,0)
 
+
Applicability is (ISG)
      Applicability is (G)
+
|-
 
+
|PDTA_SparseTable  
  PDTA_NumColors                         (uint32)
+
|(uint8 *)
      The number of colours in the palette (PDTA_CRegs) for the source
+
|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.
      picture or PDTA_BitMap.
+
Defaults to NULL.
 
+
Applicability is (I).
      Applicability is (ISG)
+
|-
 
+
|PDTA_NumSparse
  PDTA_NumAlloc                           (uint32)
+
|(uint16)
      The number of colours allocated to the palette (PDTA_GRegs) for the
+
|The number of pens in the sparse colour table PDTA_SparseTable.
      remapped BitMap (PDTA_DestBitMap).
+
Defaults to 0.
 
+
Applicability is (I)
      Applicability is (G)
+
|-
 
+
|PDTA_UseFriendBitMap
  PDTA_Remap                             (BOOL)
+
|(BOOL)
      Indicates whether the picture should be remapped or not during the
+
|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().
      layout process.  When not remapped, the bitmap (PDTA_DestBitMap)
+
Defaults to TRUE.
      produces will be (almost) identical to the source BitMap.
+
Applicability is (ISG)
 
+
|-
      Defaults to TRUE.
+
|PDTA_AlphaChannel
      Applicability is (I)
+
|(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.
  PDTA_Screen                             (struct Screen *)
+
Defaults to FALSE.
      A pointer to a Screen structure representing the screen to remap
+
Applicability is (IG)
      the picture to.  Only used if the picture object is not added to
+
|-
      a Window; primarily used when calling DTM_OBTAINDRAWINFO in order
+
|PDTA_MaskPlane  
      to remap the picture.
+
|(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.
+
Defaults to NULL.
      Applicability is (IS)
+
Applicability is (G)
 
+
|-
  PDTA_FreeSourceBitMap                   (BOOL)
+
|PDTA_PromoteMask
      Indicates whether the source bitmap should be freed immediately
+
|(BOOL)
      after the layout (remapping) method has finished.
+
|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.
      When PDTA_SourceMode = PMODE_V42, this will free the BitMap
+
Defaults to FALSE.
      specified in PDTA_BitMap; for PDTA_SourceMode = PMODE_V43, this
+
Applicability is (ISG)
      will free the internal BitMap representing the pixel buffer.
+
|-
 
+
|PDTA_WhichPicture
      Defaults to FALSE.
+
|(uint32)
      Applicability is (ISG)
+
|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.
  PDTA_Grab                               (Point *)
+
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.
      A pointer to a Point structure that specifies the grab point of
+
Defaults to 0.
      the picture.
+
Applicability is (I)
 
+
|-
      Defaults to (0,0)
+
|PDTA_GetNumPictures
      Applicability is (ISG)
+
|(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.
  PDTA_SparseTable                       (uint8 *)
+
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.
      An array of pen numbers indicating which colours should be used when
+
Defaults to NULL.
      remapping the picture.  This array MUST contain at least as many
+
Applicability is (I)
      entries as indicated by PDTA_NumSparse.  These are the pre-allocated
+
|-
      pens to be used as a replacement to quantization; the remapped colour
+
|PDTA_MaxDitherPens
      registers in PDTA_GRegs will be populated with the pen RGB colours.
+
|(uint32)
 
+
|The maximum number of pens to use during colour quantization.  
      Defaults to NULL.
+
NOTE that some quantization algorithms require a power of two for optimal results.
      Applicability is (I).
+
Defaults to 125.
 
+
Applicability is (ISG)
  PDTA_NumSparse                         (uint16)
+
|-
      The number of pens in the sparse colour table PDTA_SparseTable.
+
|PDTA_DitherQuality
 
+
|(uint32)
      Defaults to 0.
+
|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.
      Applicability is (I)
+
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.
  PDTA_UseFriendBitMap                   (BOOL)
+
Applicability is (ISG)
      If set to TRUE, any BitMap allocations will be performed using a
+
|-
      'friend' BitMap, typically from the Screen to which the picture
+
|PDTA_ScaleQuality
      is being remapped.  See graphics.library/AllocBitMap().
+
|(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 TRUE.
+
Defaults to 0.
      Applicability is (ISG)
+
Applicability is (ISG)
 
+
|-
  PDTA_AlphaChannel                       (BOOL)
+
|PDTA_ObtainPixelBuffer
      Analogous to mskHasAlpha in the bmh_Masking field of the BitMapHeader.
+
|(struct pdtBlitPixelArray *)
      Is set to TRUE, indicates that the source picture has an alpha channel.
+
|Provided for OS 3.2 compatibility and is the equivalent of the PDTM_OBTAINPIXELARRAY method.
 
+
Applicability is (S)
      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)
 
  
  

Revision as of 14:04, 4 March 2024

TABLE OF CONTENTS

picture.datatype
picture.datatype/PDTM_QUANTIZEPIXELARRAY
picture.datatype/PDTM_SCALE
picture.datatype/PDTM_SCALEPIXELARRAY
picture_dtc/OM_DISPOSE
picture_dtc/OM_GET
picture_dtc/OM_NEW
picture_dtc/OM_SET


picture.datatype

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

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 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_QUANTIZEPIXELARRAYture.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 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 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 picture_dtc/OM_DISPOSE

NAME
   OM_DISPOSE -- Dispose an instance of a document class object.
SYNOPSIS
   result = OM_DISPOSE(class, obj, msg)
   uint32 OM_DISPOSE(Class *, Object *, Msg)
FUNCTION
  Dispose of the specified document class 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 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 picture_dtc/OM_NEW

NAME
   OM_NEW -- Initialise a new instance of a document class object.
SYNOPSIS
   result = OM_NEW(class, obj, msg)
   uint32 OM_NEW(Class *, Object *, struct opSet *)
FUNCTION
  Initialise a new instance of a document class 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 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>