OP_PNGE: Expand PNG to DIB or Raw

See the PNG_UNION:OP_PNGE section for additional information.  Note that OP_PNGE requires that ParmVerMinor be 2 or 4.

OP_PNGE is used for expanding standard .PNG images.

For PNG images, the bit depth of the output DIB is the same as that of the input compressed image unless the F_Bmp flag is set or due to side effects of the PF2_RetrieveAlpha flag.  If the F_Bmp flag is set, any 16-bit pixel components are converted to 8-bit components.  If the PF2_RetrieveAlpha flag is not set, the output bit depth may be reduced to remove an alpha channel. If the PF2_RetrieveAlpha flag is set, the output bit depth may be increased to a more convenient size.

u.PNG.Region is set by OP_PNGE during REQ_INIT.  The region values reflect the values in the IHDR chunk and any PLTE (palette) chunk of the PNG file.  In the case the F_Bmp flag is set, the Head structure will also be set as appropriate for a BMP image.  (Note that when F_Bmp is set, 16-bit pixel components will be converted to 8-bit components so Head.biBitCount and u.PNG.Region.Bpp will be half the original values in that case.)

u.PNG.StripSize will have been set by OP_PNGE after REQ_INIT is complete.  The Put queue must be at least u.PNG.StripSize bytes in length.  Q_REVERSE is not supported for the Get queue. Q_REVERSE is supported for the Put queue and should normally be set if the F_Bmp flag is set.

If the PNG file has a PLTE chunk then the ColorTable is set to the corresponding Red, Green, and Blue values.  If the PNG file has both PLTE and tRNS (transparency) chunks, then the ColorTable will also contain alpha values in the rgbReserved fields.  Red and Blue are swapped if the RF_SwapRB flag is set in u.PNG.Region.Flags.  The number of colors is placed in the Head.biClrUsed field.

PF_IsColorMapped will be set for PNG images that are color-mapped.  PF_IsGray will be set for PNG images that are represented within the file as gray or for color-mapped images whose palette contains only shades of gray.  PF2_HaveAlpha will be set for PNG images that have an alpha channel or transparency information (tRNS chunk).

OP_PNGE optionally returns text (comments, application data, etc.) using PIC2List packets. Therefore OP_PNGE requires that ParmVerMinor equals 2 or 4.  See the PIC2List section of Accessing Comments and Other Auxiliary Data in the PICTools and AIMTools Programmer's Guide for more information about how opcodes return PIC2List packets.

Certain other u.PNG fields may be useful to an application.  They may be ignored by the user.  The values are retrieved from the image and returned to the application by OP_PNGE.  For more information about these fields, see the PNG_UNION:OP_PNGE section.  These fields are: u.PNG.Filter, u.PNG.Interlace, u.PNG.BackgroundColorRGB, u.PNG.TransparentColorRGB, and u.PNG.BackgroundColorIndex.

PF2_RetrieveAlpha should be set in u.PNG.PicFlags2 if the opcode should return data with an alpha channel or transparency mask.  Alpha or transparency information is conveyed within a tRNS (transparency) chunk in the PNG file.  If this flag is set, the image will be returned in one of two different forms: RGB plus alpha (32 or 64 bits per pixel in the PUT queue.)  Any image which does not match one of these formats will be automatically converted to the closest format.

PF2_RetrieveAlpha can also be set after REQ_INIT but before REQ_EXEC. In that scenario u.PNG.StripSize and u.PNG.Region.Stride will have to be corrected to correspond to an output image with Alpha information.  u.PNG.AlphaStride can be used for this correction as shown in the example code below:

This scenario is useful if the application does not know in advance if an image has an Alpha channel and it is trying to avoid setting PF2_RetrieveAlpha for an image that does not have alpha.

PF_IsGray and PF_IsColorMapped can be examined to determine the original form of a converted image. If PF2_RetrieveAlpha is not set, the image will be returned in its native format.  Alpha values will have the same range as a component of a pixel: 0-255 for 8-bit components and 0-65,535 for 16-bit components.  0 indicates a fully transparent pixel and 255 or 65,535 indicates a fully opaque pixel.

In order to support larger images, this opcode supports the optional use of REGION2.  If ParmVerMinor is set to 4, then the opcode treats u.PNG.Region as a REGION2 structure instead of a REGION structure.  Otherwise, ParmVerMinor should be set to 2.  See the REGION2 section for more information

The input image can be cropped using F_Crop and CropXoff, CropYoff, CropWidth, and CropHeight.  If the F_Crop flag is added after REQ_INIT, you must adjust u.PNG.StripSize and u.PNG.Region.Stride.