PICTools Programmer's Reference
HDP_UNION
Operation Structures > HDP_UNION

HDP_UNION: OP_HDPHOTOP, OPHDPHOTOE

The HDP_UNION structure supplies parameters to the OP_HDPHOTOP and OP_HDPHOTOE opcodes used for compressing images to JPEG XR and expanding JPEG XR images, respectively. These opcodes can also be used for compressing and expanding the older Microsoft HD Photo images

 
Copy Code 
typedef struct {
   DWORD                  Reserved0;
   DWORD PICHUGE*         TileWidths;
   DWORD PICHUGE*         TileHeights;
   BYTE PICHUGE*          Reserved3;
   BYTE PICHUGE*          Reserved4;
   BYTE PICHUGE*          Reserverd5;
   BYTE PICHUGE*          Reserved6;
   BYTE PICHUGE*          Reserved7;
   BYTE PICHUGE*          Reserved8;
   PICFLAGS               PicFlags;
   PICFLAGS               PicFlags2;
   REGION2                Region;
   DWORD                  OrigWidth;
   DWORD                  OrigHeight;
   double                 WidthResolution;
   double                 HeightResolution;
   LONG                   StripSize;
   LONG                   LibraryError;
   THUMBNAIL              Thumbnail;
   ORIENTATION            Reorient;
   DWORD                  PostProcessingFilter;
   BYTE PICHUGE*          PixelFormat;
   DWORD                  Quantization;
   DWORD                  ChromaSubsampling;
   DWORD                  Overlapping;
   DWORD                  FrequencyOrdering;
   DWORD                  TrimmedFlexbits;
   DWORD                  SkipSubbands;
   DWORD                  NumHorizontalTiles;
   DWORD                  NumVerticalTiles;
   DWORD                  AlphaQuantization;
   DWORD                  AlphaChannelStructure;
   DWORD                  Enhancements;
} HDP_UNION;

Fields:

Name Description

Reserved0

This field is not currently used and must be set to 0.

TileWidths

(OP_HDPHOTOP) This field is used for non-uniform tiling.  JPEG XR allows an image to be subdivided into individual tiles.  The main purpose of tiling is to optimize an image for region decoding. With non-uniform tiling, the desired height and width for each tile row and column can be specified. This field points to an array of DWORDS, with each entry specifying a tile width (in macro blocks, a macro block is 16 pixels).  The maximum allowable tile width is 65535.  If insufficient values are specified to describe the entire width of the image, the right-most column will be sized to contain the remaining pixels  If the array exceeds the dimension of the image, the extra entries in the array will be ignored.  The field NumHorizontalTiles indicates the number of entries in the array. No more than 4096 tile widths may be specified.

TileHeights

(OP_HDPHOTOP) This field is used for non-uniform tiling.  This field points to an array of DWORDS, with each entry specifying a tile height (in macro blocks, a macro block is 16 pixels).   The maximum allowable tile height is 65535. If insufficient values are specified to describe the entire height of the image, the bottom-most row will be sized to contain the remaining pixels.   If the array exceeds the dimension of the image, the extra entries in the array will be ignored.  The field NumVerticalTiles indicates the number of entries in the array.  No more than 4096 tile heights may be specified.

Reserved3

Reserved4

Reserved5

Reserved6

Reserved7

Reserved8

These fields are not currently used and must be set to 0.

PicFlags

Flags that report on the OP_HDPHOTOE operation.

Value

Meaning

PF_IsGray

(OP_HDPHOTOE) Set if the original image is a single component gray image.

PicFlags2

Flags that report on the OP_HDPHOTOE operation.

Value

Meaning

PF2_HaveAlpha

Set if the original image had alpha channel information.

PF2_JPEGXR_Format 

Set if the input compressed image used the ISO Standard JPEG XR compression (vs. older HD Photo standard)

PF2_HardTileEdges

Set if the input compressed image disabled overlap filtering across tile boundaries.

PF2_SkipJPEGXRHeader

Set if the input compressed image was JPEG XR a codestream without the JPEG XR container.

Flags that control the OP_HDPHOTOP operation.

Value

Meaning

PF2_JPEGXR_Format

Use ISO-Standard JPEG XR compression (vs. older HD Photo standard)

PF2_HardTileEdges

PF2_SkipJPEGXRHeader

(JPEG XR mode only). Disable overlap filtering across tile boundaries.

(JPEG XR mode only). Generate a codestream without the JPEG XR container.

Region

This REGION2 field is used to define image characteristics. OP_HDPHOTOE returns the image characteristics in this structure following REQ_INIT in addition to returning them in the PIC_PARM.Head structure. 

For OP_HDPHOTOE, if you change parameters such as Thumbnail, Reorient, or cropping between REQ_INIT and REQ_EXEC, and have not initialized the Put queue pointers, then OP_HDPHOTOE will update the Region fields and StripSize before RES_PUT_NEED_SPACE is returned.  Then if a change to the Region.Stride and StripSize is required to accommodate row padding, it may be specified in the first RES_PUT_NEED_SPACE call.

OP_HDPHOTOP requires that the Region fields be set before the call to REQ_INIT if F_Raw is set in the PIC_PARM.Flags field.  There are some PixType values added for new pixel formats supported by HD Photo, so be sure to look over the REGION2 structure information.

OrigWidth

(OP_HDPHOTOE) The true width of the image, before cropping and thumbnailing.  This is returned from REQ_INIT.

OrigHeight

(OP_HDPHOTOE) The true height of the image, before cropping and thumbnailing.  This is returned from REQ_INIT.

WidthResolution

(OP_HDPHOTOP) Set to the width resolution of the image in pixels per inch before calling REQ_INIT.

(OP_HDPHOTOE) The width resolution of the image in pixels per inch.  This is returned from REQ_INIT.  WidthResolution and HeightResolution are swapped if needed because of image rotation because the input image's orientation information or because of the Reorient field.  So WidthResolution reflects the width resolution after any rotation.

HeightResolution

(OP_HDPHOTOP) Set to the height resolution of the image in pixels per inch before calling REQ_INIT.

 (OP_HDPHOTOE) The height resolution of the image in pixels per inch.  This is returned from REQ_INIT.  WidthResolution and HeightResolution are swapped if needed because of image rotation because the input image's orientation information or because of the Reorient field.  So HeightResolution reflects the height resolution after any rotation.

StripSize

Specifies the minimum buffer size needed to hold one strip of output data (OP_HDPHOTOE) or input data (OP_HDPHOTOP). Currently, streaming output of uncompressed data is not supported, so for OP_HDPHOTOE strip size will be set to the size needed to contain the entire output image. This is provided to the caller after REQ_INIT has been invoked. For OP_HDPHOTOP, the Get queue must be at least large enough to hold this number of bytes. For OP_HDPHOTOE, the Put queue must be at least large enough to hold this number of bytes.

LibraryError

Indicates the specific error reported by the JPEG XR library when ERR_LIBRARY_ERROR is returned in Status.

Thumbnail

(OP_HDPHOTOE) This can be used to specify faster decompression to a thumbnail image.  The width and height of the output image are each reduced by (1/2)^Thumbnail (rounded up) down to a minimum size of one pixel.

Reorient

(OP_HDPHOTOP) The orientation is embedded in the file container and applied during decompression.

(OP_HDPHOTOE) This can be used to reorient the image during decompression.  REORIENT_FROM_IMAGE specifies that the output image should be rotated according to the input image's orientation information.  Otherwise 0 does no rotation, and other ORIENTATION values rotate accordingly.

PostProcessingFilter

(OP_HDPHOTOE) This is used to specify the post processing filter strength.  Allowable values are 0 (none), 1 (light), 2 (medium), 3 (strong), 4 (very strong).

PixelFormat

(OP_HDPHOTOE) The JPEG XR GUID for the image.  This is returned from REQ_INIT.

Quantization

(OP_HDPHOTOP) The amount of quantization determines the desired image quality by defining the amount of similar image data that can be discarded.  The quantization can range from 1-255.  Lower quantization values specify a higher image quality, while higher quantization values specify lower image quality.  A value of one is used to specify lossless compression.

ChromaSubsampling

Chroma sub-sampling is used to reduce the resolution of the color information (as contrasted with the luminance information) in an image prior to the quantization process.  Chroma sub-sampling can be an effective way to reduce image content with little perceptible degradation because the human eye is less sensitive to the resolution of color information than it is to the resolution of luminance information.

(OP_HDPHOTOP) These values are used to specify the subsampling to be used by the compressor.

(OP_HDPHOTOE) These values are used to indicate the subsampling that was used when the image was compressed.

The following values are allowed for this field:

Value

Meaning

HDP_SS_444

4:4:4 no sub-sampling (default)

HDP_SS_422_COSITED

4:2:2 sub-sampling (sub-samples 2:1 horizontally with cosited chroma samples with respect to luma samples)

HDP_SS_422_CENTERED

4:2:2 sub-sampling (sub-samples 2:1 horizontally with centered chroma samples with respect to luma samples)

(For compression, only allowed in JPEG XR mode)

HDP_SS_422_OTHER

(HD_PHOTOE only) 4:2:2 sub-sampling (sub-sampled 2:1 horizontally with chroma samples using an x/y offset with respect to luma samples that is neither cosited nor centered)

HDP_SS_420_COSITED

4:2:0 sub-sampling (sub-samples 2:1 horizontally and 2:1 vertically with cosited chroma samples with respect to luma samples)

HDP_SS_420_CENTERED

4:2:0 sub-sampling (sub-samples 2:1 horizontally and 2:1 vertically with centered chroma samples with respect to luma samples) (For compression, only allowed in JPEG XR mode)

HDP_SS_420_OTHER

(HD_PHOTOE only) 4:2:0 sub-sampling (sub-sampled 2:1 horizontally and 2:1 vertically with chroma samples using an x/y offset with respect to luma samples that is neither cosited nor centered)

HDP_SS_400

4:0:0 sub-sampling (discards all color information)

Overlapping

(OP_HDPHOTOP) Overlap processing takes into account the values of pixels in neighboring blocks and macro blocks when choosing the quantization values that represent similar adjacent pixels.  This is intended to reduce the visible differences among adjacent blocks and macro blocks.  The following values are allowed for this field:

Value

Meaning

HDP_OL_SINGLE

Single overlap processing is performed at the 4x4 block level.  This is the default and should be used for most typical encoding scenarios.

HDP_OL_DOUBLE

Double level overlap processing also analyzes adjacent pixels at the 16x16 macro block level.  For very high quantization levels, this may be appropriate, but it may result in a loss of image detail and it is slower than HDP_OL_SINGLE.

HDP_OL_NONE

This suppresses all overlap processing.  This may speed up processing, but is only recommended for very low quantization levels.

FrequencyOrdering

(OP_HDPHOTOP) JPEG XR makes it possible to organize the compressed image data sequentially in either spatial or frequency order.  The sequential compressed data stream represents the image in macro block rows starting at the upper left corner, from left to right and from top to bottom.  Frequency order groups the data in three different frequencies and places it sequentially in the file starting with the low frequency information, followed by the middle frequency, and finally by the high frequency. Frequency order makes it more efficient to decode a low resolution or thumbnail version of the image.  The default is spatial ordering.  Set this field to a value of 1 to request frequency ordering.

TrimmedFlexbits

(OP_HDPHOTOP) Specify a value between 0 and 15, with 0 (the default) indicating no trimming and 15 indicating trim all.

SkipSubbands

(OP_HDPHOTOP) This field specifies which subbands to skip.  The following values are allowed:

Value

Meaning

HDP_SB_ALL

All subbands included (default)

HDP_SB_SKIPFLEX

Skip flexbits.

HDP_SB_SKIPHIGH

Skip highpass

HDP_SB_SKIPHIGHLOW

Skip highpass & lowpass (DC only)

NumHorizontalTiles

(OP_HDPHOTOP) This field is used in support of both uniform and non-uniform tiling.  With uniform tiling, all tiles share the same width and height.  With non-uniform tiling, the desired height and width of each tile row and column can be specified.

To specify uniform tiling, set this field to a non-zero value, and leave the TileWidths array set to zero.  The image will be sliced into the requested number of columns, spacing them as evenly as possible.  Tiles are always a multiple of macro blocks (16x16), except for the right column of tiles. Note that an image is always composed of at least a single tile, so the minimum value for this field is one.

To specify non-uniform tiling, allocate and populate the TileWidths array.  This field should be set to the number of entries in the array.  A maximum of 4096 tiles may be specified.

NumVerticalTiles

(OP_HDPHOTOP) This field is used in support of both uniform and non-uniform tiling.  With uniform tiling, all tiles share the same width and height.  With non-uniform tiling, the desired height and width of each tile row and column can be specified.

To specify uniform tiling, set this field to a non-zero value, and leave the TileHeights array set to zero.  The image will be sliced into the requested number of rows, spacing them as evenly as possible.  Tiles are always a multiple of macro blocks (16x16 pixels), except for the bottom row of tiles.  Note that an image is always composed of at least a single tile, so the minimum value for this field is one.

To specify non-uniform tiling, allocate and populate the TileHeights array.  This field should be set to the number of entries in the array.  A maximum of 4096 tiles may be specified.

AlphaQuantization

(OP_HDPHOTOP) This field is used to specify the desired quantization level for the planar alpha channel.  For HD Photo compression mode, It is only used when the AlphaChannelStructure is set to planar. For JPEG XR compression mode, it can also be used for interleaved alpha channels. The quantization can range from 1-255.  Lower quantization values specify a higher image quality, while higher quantization values specify lower image quality.  A value of one is used to specify lossless compression.

AlphaChannelStructure

(OP_HDPHOTOP) HD Photo supports both interleaved and planar alpha channels.  An interleaved alpha channel is stored in sequence with the channels that describe the image contents.  A planar alpha channel is stored as a separate image and is encoded separately from the RGB or CMYK data. The following values are allowed:

Value

Meaning

HDP_ALPHA_PLANAR

Planar alpha channel (default)

HDP_ALPHA_INTERLEAVE

Interleaved alpha channel

Enhancements

(OP_HDPHOTOP) This field specifies which (if any) enhanced quantization mode is to be used.

Value

Meaning

HDP_OPTIMIZE_NONE

No quantization enhancement mode.(default)

HDP_OPTIMIZE_FOR_VISUAL

Use quantization optimized for visual quality (i.e., can provide better visual quality while allowing higher Quantization values).

HDP_OPTIMIZE_FOR_SSIM

Use quantization adjusted for the SSIM visual index.

HDP_OPTIMIZE_FOR_SNR

Use adaptive quantization optimized for PSNR.

 

 

©2022. Accusoft Corporation. All Rights Reserved.

Send Feedback