PICTools Programmer's Reference

OP_F2D, OP_F2DPLUS: Convert image file format to DIB

See the F2D_STRUC: OP_F2D, OP_F2DPLUS section for additional information. Supported input image file formats are Bitmap, PBM, PGM, PPM, PNM, DCX, PCX, ICON, WBMP, TIFF, Raw Fax, and Targa.  OP_F2DPLUS also supports GIF and TIFF/LZW formats.

General Notes

• F_RelaxedQueue should be always OR'ed into PicParm.Flags for OP_F2D. When the flag is set, the behavior of its Get and Put queues is the same as for all other opcodes except for OP_UTL.
• The image data output to the Put queue is either a DIB or a BMP file image (starting after the 14-byte BITMAPFILEHEADER).  If the output is to be a BMP file image including the BITMAPINFOHEADER and color table, then PF_IncludeBMPHead must be set in F2D.PicFlags.  Whether or not PF_IncludeBMPHead is set, F2D.BiOut is initialized to the BITMAPINFOHEADER data describing the output image and ColorTable is initialized to the output image color table, if any.
• Each line of pixels in the output image will be padded to a DWORD boundary if needed.
• If the input image, and therefore the output image, is a gray scale image -- that is if the input image has a color table and if all the colors in the color table are shades of gray - then when OP_F2D is complete, PF_IsGray will be set in F2D.PicFlags.
• F2D.AuxSpace may be set to point to a block of memory whose size is F2D.AuxSize.  Data may be returned by OP_F2D in this block of memory organized as a sequential series of one or more "chunks".  Each chunk consists of a DWORD Tag, followed by a DWORD Length, followed by Length bytes of data. Thus the total length of each chunk is Length + 8.  Whenever OP_F2D places data in F2D.AuxSpace, it sets AuxUsed to the total length consumed in F2D.AuxSpace.  F2D.AuxSpace is currently not used for PCX input files. See the following sections for additional information specific to an input file format.

Deprecated Queue Behavior

• If F_RelaxedQueue is not set in PicParm.Flags, OP_F2D's Get and Put queue behavior requires some additional considerations described below. This deprecated behavior has been retained to provide backwards compatibility to existing applications that expect it when using the opcode. New applications should set F_RelaxedQueue which allows using OP_F2D in a manner consistent with all the other opcodes except for OP_UTL.
• If F_RelaxedQueue is not set in PicParms.Flags and the Get queue is large enough for the entire input image, the flag F2D.AllocType should be set to 1. In this case, with F2D.AllocType set to 1, any input queue RES_SEEK response can be handled as:

• Also if F2D.AllocType is 1, the Get queue size must be, or must appear to be, at least one byte larger than the size of the image.  Since the extra byte will not be accessed by OP_F2D, this might be coded as:

Get.Front will be advanced by OP_F2D as it examines the input image data to create the output image.  However the image data will not actually have been consumed by OP_F2D so the data between Get.Start and Get.Front must not be modified.

Similarly, the Put queue size must be at least one byte larger than the size of the image. For example: 

BMP Input

Whether or not PF_IncludeBMPHead is set, the input BMP supplied to the Get queue must include the BITMAPINFOHEADER and color table when applicable.  Older-format BMP files with a BITMAPCOREHEADER instead of a BITMAPINFOHEADER are also supported.  The only field in Head which must be initialized according to the input image is Head.biCompression.  No input image color table need be in ColorTable.

The input image may be 1, 4, 8, 16, 24 or 32 bits-per-pixel. The output BMP is 24 bits-per-pixel for 16 and 32 bits-per-pixel input images.  Otherwise the output BMP bit depth is the same as the input image bit depth.

4 or 8-bit input images may be uncompressed or RLE compressed.  Other input image bit depths must be uncompressed.

If F2D.AuxSpace is not 0 and F2D.AuxSize is not 0, then any extra data present in the input BMP following the color table and preceding the image DIB bits is returned as an AUX_BMP_EXTRABI chunk.  See the OP_D2F BMP Output section for additional discussion about this data.

If this AUX_BMP_EXTRABI data is exactly 24 bytes of zeroes, then the input BMP is an OS/2 2.1-compatible bitmap file.

Otherwise, the AUX_BMP_EXTRABI data could have been used to embed an image comment or image annotation into the input image.

PCX Input

The input image may be 1, 4, 8 or 24 bits-per-pixel. The output BMP bit depth is the same as the input image bit depth. F2D.AuxSpace is ignored for PCX input.

OP_F2D supports version 3.0 PCX files (PCX image header version field has the value 5).

Targa Input

The following Targa input image types are supported:

• Type 1: uncompressed 1, 4 or 8 bits-per-pixel palletized
• Type 2: uncompressed 1, 4 or 8 bits-per-pixel gray scale
• Type 3: uncompressed 16, 24 or 32 bits-per-pixel RGB color
• Type 9: RLE-compressed 1, 4 or 8 bits-per-pixel palletized
• Type 10: RLE-compressed 1, 4 or 8 bits-per-pixel gray scale
• Type 11: RLE-compressed 16, 24 or 32 bits-per-pixel RGB color

The output BMP bit depth is the same as the input image bit depth.

OP_F2D supports the Targa version 2.0 specification.

If F2D.AuxSpace is not 0 and F2D.AuxSize is not 0, then data from the Image ID, the Developer Area and the Extension Area are output as chunks to the F2D.AuxSpace buffer.  If an Image ID is present, it is output with a tag of AUX_TGA_COMMENT.  If Developer Fields are present in the Targa image, then the total number of Developer Fields is output with a tag of AUX_TGA_DEVELOPER_COUNT.  The Developer Fields themselves are each output with a tag of AUX_TGA_DEVELOPER   If an Extension Area is present, then 495 bytes are output with a tag of AUX_TGA_EXTENSION.  The first 490 bytes contain the first 490 bytes of the Extension Area.  The last 5 bytes are output as 0.

Raw Fax

Set Head.biCompression to BI_G3 or BI_G32D to convert raw fax input images to DIB format.  Up to 32768 pixels per scan line are supported.  The output DIB is 1 bit-per-pixel.  The DIB will be upside down compared to the normal DIB orientation (thus the top screen line will be the first line in the DIB).  F2D.BiOut.biHeight and F2D.BiOut.biSizeImage will not be valid until all the input has been processed.  If PF_IncludeBMPHead is set in F2D.BiOut.PicFlags, then the BITMAPINFOHEADER biWidth, biHeight and biSizeImage fields will be output as -1.  Set RawG3FillOrder to the TIFF FillOrder corresponding to the input raw fax image.  For a raw fax, this value will ordinarily be 2 (or 0) for a FillOrder filling bytes from the least-significant-bit to the most-significant-bit.  Otherwise set RawG3FillOrder to 1 for a FillOrder filling bytes from the most-significant-bit to the least-significant-bit.  Set RawG3PhotometricInterpretation to the TIFF PhotometricInterpretation corresponding to the input raw fax image.  For a raw fax, this value will ordinarily be 0 (WhiteIsZero).  Otherwise set RawG3PhotometricInterpretation to 1 (BlackIsZero).

TIFF

The input TIFF file may contain multiple images.

• The ImageNumber field in PIC_PARM is the number of the image which is to be returned as a DIB.
  • 0 and 1 both return the first image - the image whose Image File Directory (IFD) is pointed to by the TIFF header.
  • 2 returns the image whose IFD is pointed to by the first image's IFD.
  • And so on.

The input image may be a PhotometricInterpretation type 0, 1, 2, 3, or 5 TIFF image.

• Supported Compression types include 1 (uncompressed), 2 (modified G3), 3 (G3), 4 (G4) or 32773 (Packbits).
• OP_F2DPLUS additionally supports Compression type 5 (LZW), 6 and 7 (JPEG), 8 or 32946 (ZLIB). If the compression type is 6 or 7 (JPEG) then PhotometricInterpretation type 2 (RGB) or 6 (YCBCR) is allowed.
• For JPEG decompression, this opcode uses OP_S2D, OP_SE2D, or OP_SE2DPLUS (depending on which of these opcodes is present and registered). The JPEG decompressor opcode registration data is passed to this opcode in the PicParm.PIC2List P2PktRegistration packets. See the PIC2List Functions section for more information.
• OP_F2DPLUS also supports Differencing Predictor types 1 (no predictor) and 2 (horizontal differencing predictor) for Compression type 5.
• Intel and Motorola byte ordering are supported for all types.
• The output DIB bits per pixel are the same as the input TIFF samples-per-pixel times the TIFF bits-per-sample.

The Base TIFF version 6.0 specification is supported.

• Supported extensions include CCIT Bilevel encoding only. Tiled TIFF images are not supported.
• Planar RGB TIFF images are not supported.
• Bitonal and 8bpp grayscale TIFF images with a PlanarConfiguration=1 or 2 are tolerated. Any other value encountered will also be tolerated but with a warning emitted.
• Data sample format specifications are not supported.
• TIFF images with a PhotometricInterpretation=5 (CMYK) will set the F2D.BiOut.Compression field to BI_CMYK, however no color conversion to RGB is performed.
• CIELAB images are not supported.

If F2D.AuxSpace is not 0 and F2D.AuxSize is not 0, then TIFF image data specified by TIFF tags which are not used in converting to a DIB are output as chunks to the F2D.AuxSpace buffer.  The chunk tag is AUX_TIFF_Base + the value of the TIFF tag.

The image compression method is returned as F2D.Compression.  The value is the same as the TIFF compression type as above, except that 2-dimensional G3 is returned as 3.

GIF

OP_F2DPLUS converts GIF87a and GIF89a images to DIB format.  The output DIB is always 8-bits-per-pixel.  If the GIF input file contains multiple images, only the first image is converted.  Interlaced GIF is supported.  Transparent GIF is supported.  The output DIB is always 8 bits-per-pixel.

Set PF_ApplyTransparency in PIC_PARM.u.F2D.PicFlags to honor a GIF transparent color index in the input file.  If PF_ApplyTransparency is set, then the Put queue must be large enough for the entire image.  The Put queue must already have been initialized with the image data onto which the input GIF image is being overlaid, although Put.Front and Put.Rear must be set to Put.Start as usual, denoting an empty queue.  The GIF image pixels whose color index is the same as the transparent color index will not be set in the Put queue, allowing the previous image data to show through those GIF image pixels.

If PF_ApplyTransparency is not set, and the GIF image has a transparent color index, then the DIB output pixels corresponding to the transparent GIF pixels are set to the color whose color table index is the same as the transparent color index.  Any previous image data does not show through those GIF image pixels.

If PIC_PARM.Head.biCompression is BI_GIFI, then the input image must be an interlaced GIF image.  If biCompression is BI_GIFN, then the input image must not be an interlaced GIF image.  If biCompression is BI_GIFu, then the input image may be either interlaced or not interlaced.

If the input image is interlaced, then PIC_PARM.u.F2D.ProgressiveMode may be used to specify that the image will be displayed progressively, or that only the complete image will be displayed (see table below).  If the ProgressiveMode indicates that the image will be displayed progressively, then Pegasus will return RES_DONE from Pegasus(REQ_EXEC) each time the data for the next interlace pass is complete.  When RES_DONE is returned after the final interlace pass, PF_EOIFound will be set in PIC_PARM.u.F2D.PicFlags.  PF_EOIFound will be clear when RES_DONE is returned after any other interlace pass.

When RES_DONE is returned after an interlace pass, you will ordinarily display the image data for that interlace pass from the Put queue.  You will then empty the Put queue by setting Put.Front and Put.Rear to Put.Start.  To be useful, progressive modes 1 and 4 assume that the data from the prior interlace pass remain in the Put queue.  If PF_EOIFound is not set, you will finally call Pegasus(REQ_CONT) for the image data from the next interlace pass.

ProgressiveMode	Meaning
0	RES_DONE is returned four times.  The first DIB returned is 1/8 the height of the full image.  The second DIB returned is 1/4 the height of the full image.  The third DIB returned is 1/2 the height of the full image.  The final DIB returned is the complete image at full size.
1	RES_DONE is returned four times.  Each returned DIB is the same size as the complete, full-size image.  The first DIB has every 8th line, the second DIB has every 4th line and the third DIB has every 2nd line.  In each case, the lines between the interlace pass lines are filled with copies of the preceding interlace pass line. The final DIB is the complete image at full size.
2	RES_DONE is returned once.  The returned DIB is the complete image at full size.
3	RES_DONE is returned four times.  Each returned DIB is the same size as the complete, full-size image.  The first DIB has every 8th line, the second DIB has every 4th line, the third DIB has every 2nd line and the fourth DIB is the complete image.  The first DIB fills in the lines between each 8th line with copies of the preceding line.  The second DIB adds image data from the second interlace pass to the first DIB.  The third DIB adds image data from the third interlace pass to the second DIB.  The final DIB adds image data from the fourth interlace pass to the third DIB.  Only the first DIB fills in the lines between the current interface pass lines.

 

If PF_MultiImage is set after REQ_EXEC/RES_DONE for a frame, then the GIF trailer did not immediately follow the frame, and there may be additional frames.

If F2D.AuxSpace is not 0 and F2D.AuxSize is not 0, then extension GIF image data are returned if present.  The AUX data includes the entire GIF extension data are returned beginning with the extension introducer '!'.  The AUX tag AUX_GIF_1 is used for the graphics control extension.  AUX_GIF_2 is used for the plain text extension.  AUX_GIF_3 is used for application extensions.  AUX_GIF_4 is used for comment extensions.  Only extensions which precede the first image are returned in a multi-image GIF file