PICTools Programmer's Reference
OP_HDPHOTOE
| Operations > OP_HDPHOTOE |
OP_HDPHOTOE: Decompress HD Photo image
The purpose of OP_HDPHOTOE (see opcode specific data structure) is to decompress images that were compressed according to the ISO JPEG XR Image Coding Specification. It also decompresses images that were compressed according to the older Microsoft HD Photo specification. HD Photo (formerly known as Windows Media Photo) was adopted by ISO as a standard compression format in 2009 and was renamed JPEG XR (ISO/IEC 29199-2). It was also given some additional enhancements, e.g. additional image formats, and an improved overlap filter (used in the Hadamard transform). JPEG XR is an image compression algorithm and file format that is designed for use with continuous tone images, such as photographs. It provides lossless or lossy compression and supports a wide range of pixel formats, including bilevel, gray, RGB, and CMYK, using up to 16-bit integer representation, or up to 32-bit fixed or floating point representation. JPEG XR also supports several packed bit formats, including 5 or 10bpc RGB and RGBE/Radiance.
The file format used by JPEG XR is based on the TIFF format. Image data is stored in a table of Image File Directory (IFD) tags. A JPEG XR file contains image data, optional alpha channel data, HD Photo metadata, optional XMP metadata, and optional Exif metadata. The opcode reads the JPEG XR image data from the Get queue and decompresses it and writes the uncompressed pixel values to the Put queue.
The input image is provided in the Get queue. The input image may be streamed, i.e. the Get queue can be as small as one byte; however, that's not recommended because it will be very inefficient and therefore slow. The input image characteristics are returned in u.HDP.Region after REQ_INIT returns RES_DONE, before any uncompressed image data is returned. In particular, Region.PixType and Region.Flags together describe the characteristics of the decompressed output pixels. These characteristics include the color space of the pixels, whether or not alpha channel information is present, and how the individual color component samples are to be interpreted, and how many bits are used to represent each sample. The samples may be 8-bit or 16-bit unsigned integers, 16-bit or 32-bit Microsoft fixed point, or 16-bit or 32-bit floating point. There are also special formats for bilevel (1-bit black and white), RGB555, RGB565, RGB101010, and Radiance .HDR (shared-exponent RGB). In addition to RGB and CMYK, n-channel images with up to 8 independent channels (with or without an alpha channel) are supported for 8 or 16 bit unsigned integer samples. See the PixType table in the Region2 structure reference and the PixelFormat table in the OP_HDPHOTOP Input Image notes for additional information.
The input image may include metadata that may include DocumentName, ImageDescription, Make, Model, PageName, PageNumber, Software, DateTime, Artist, HostComputer, Copyright, RatingStars, RatingValue, Caption, XMPMetadata, ICCProfile, EXIFMetadata, GPSInfoMetadata, IPTCNAAMetadata, PhotoshopMetadata, and InteroperabilityIFD. If present, these metadata items can be optionally returned in PIC_PARM.PIC2List packets. See include\pic2file.h and the PIC2List section of Accessing Comments and Other Auxiliary Data in the PICTools and AIMTools Programmer's Guide for more information about PIC2Listpackets.
StripSize is returned after REQ_INIT and is the minimum size needed for the Put queue. It is presently set to the full size of the uncompressed image and the output from OP_HDPHOTOE is not streaming. It does not take any row-padding requirements into account.
The image characteristics described by Region fields as well as StripSize reflect any image rotation (specified by Reorient), image thumbnailing (specified by Thumbnail), and cropping (specified by PIC_PARM.IOCropXoff, PIC_PARM.IOCropYOff, PIC_PARM.IOCropWidth, PIC_PARM.IOCropHeight with F_InputCrop or F_OutputCrop set in PIC_PARM.Flags) according to the values of the respective fields when REQ_INIT is called.
You can change these parameters between REQ_INIT's return of RES_DONE and your call of REQ_EXEC.
If you have not initialized the Put queue pointers before REQ_EXEC, then the updated values of Region and StripSize will be available to you when RES_PUT_NEED_SPACE is returned for you to allocate your Put queue. Parameters such as u.HDP.Region.Stride (which is the number of bytes per image row), and StripSize may be adjusted at this time. Changing Stride and StripSize when RES_PUT_NEED_SPACE is returned is necessary if you want row padding that is different from the default and you change the image orientation so that the value of Width changes, or you decompress to a thumbnail size. The default row padding is no padding except that 1-bit Bitonal, 8-bit Gray, 24-bit RGB, RGB555 and RGB565 default to rows padded to DWORD boundaries.
Also, if the output image is 16 or 32 bit fixed or floating point RGB, you may opt to generate an output image with a fourth 'padding' channel by changing the u.HDP.Region.Bpp value from 48 to 64, or from 96 to 128 bpp before REQ_EXEC.
You can also set PostProcessingFilter any time before REQ_EXEC, but that setting doesn't affect the image characteristics returned in Region and StripSize.
Pixel format conversions are not currently supported so the pixel format of the decompressed image will be the same as the pixel format of the input compressed image which is the same as the pixel format of the original uncompressed image provided to the compressor that created the JPEG XR image. See the table in the following OP_HDPHOTOP section for a list of all pixel formats.