DIB_OUTPUT

DIB_OUTPUT: OP_S2D, OP_SE2D, OP_SE2DPLUS, OP_P2D

The DIB_OUTPUT structure contains the parameters for expanding a sequential JPEG image to a DIB using the OP_S2D opcode.

	Copy Code
typedef struct { DWORD Reserved0; BYTE PICHUGE* AppField; BYTE PICHUGE* MadeColorTable; BYTE PICHUGE* PrecisionReq; BYTE PICHUGE* ColorMap; BYTE PICHUGE* ExifThumbnail; BYTE PICHUGE* GrayMap12Bit; BYTE PICHUGE* Reserved7; BYTE PICHUGE* Reserved8; PICFLAGS PicFlags; PICFLAGS PicFlags2; LONG DibSize; THUMBNAIL Thumbnail; LONG NumScansReq; LONG NumScansDone; LONG NumBytesDone; LONG GraysToMake; LONG PrimClrToMake; LONG SecClrToMake; LONG StripSize; LONG WidthPad; LONG LumFactor; LONG ChromFactor; SUBSAMPLING SubSampling; JPEG_TYPE JpegType; LONG AppFieldSize; LONG AppFieldLen; LONG NumOfPages; LONG PageNum; LONG Context; LONG DitherType; LONG YuvOutputType; LONG ExifThumbnailLen; DWORD ResolutionUnit; DWORD XResolution; DWORD YResolution; LONG Brightness; LONG Contrast; LONG ContrastOfs; DWORD EnhanceMethod; DWORD Planar1Offset; DWORD Planar2Offset; } DIB_OUTPUT;

Copy Code

typedef struct {
   DWORD               Reserved0;
   BYTE PICHUGE*       AppField;
   BYTE PICHUGE*       MadeColorTable;
   BYTE PICHUGE*       PrecisionReq;
   BYTE PICHUGE*       ColorMap;
   BYTE PICHUGE*       ExifThumbnail;
   BYTE PICHUGE*       GrayMap12Bit;
   BYTE PICHUGE*       Reserved7;
   BYTE PICHUGE*       Reserved8;
   PICFLAGS            PicFlags;
   PICFLAGS            PicFlags2;
   LONG                DibSize;
   THUMBNAIL           Thumbnail;
   LONG                NumScansReq;
   LONG                NumScansDone;
   LONG                NumBytesDone;
   LONG                GraysToMake;
   LONG                PrimClrToMake;
   LONG                SecClrToMake;
   LONG                StripSize;
   LONG                WidthPad;
   LONG                LumFactor;
   LONG                ChromFactor;
   SUBSAMPLING         SubSampling;
   JPEG_TYPE           JpegType;
   LONG                AppFieldSize;
   LONG                AppFieldLen;
   LONG                NumOfPages;
   LONG                PageNum;
   LONG                Context;
   LONG                DitherType;
   LONG                YuvOutputType;
   LONG                ExifThumbnailLen;
   DWORD               ResolutionUnit;
   DWORD               XResolution;
   DWORD               YResolution;
   LONG                Brightness;
   LONG                Contrast;
   LONG                ContrastOfs;
   DWORD               EnhanceMethod;
   DWORD               Planar1Offset;
   DWORD               Planar2Offset;                                       
} DIB_OUTPUT;

Fields:

Name

Description

Reserved0

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

AppField

Points to a buffer to hold the application data stored with the image. This buffer is allocated and freed by the application. When expanding a JPEG image file, any APP2 data is stored into this buffer up to the size specified by AppFieldSize. If the buffer is too small, only AppFieldSize bytes are stored in the buffer. The size of the data stored is returned in the AppFieldLen field.

MadeColorTable

Points to a buffer that will can hold the color table created for a color output image when PF_MakeColors is set in PicFlags. This buffer holds an array of RGBQUAD structures that define the primary and secondary colors for the output image. The buffer must be large enough to hold the total number of RGBQUAD colors as specified by PrimClrToMake and SecClrToMake.

The MadeColorTable is only strictly necessary when both a primary and a secondary palette are desired and when the DibSize is 4. In that case, the secondary palette will be copied to ColorTable to display the DIB and the primary palette would be lost if not for MadeColorTable and if not copied in response to the RES_MADE_COLORS event.

PrecisionReq

Not used by the OP_S2D opcode and must be set to 0.

ColorMap

Not used by the OP_S2D opcode and must be set to 0.

ExifThumbnail

Points to EXIF Thumbnail data to be used as source for decompression when PF_ExpandThumbnail switch is specified.

GrayMap12Bit

(OP_SE2DPLUS) A translation table to be used to remap 12bpp grayscale data to 8bpp during decompression.

Reserved7

Reserved8

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

PicFlags

Flags that control the Pegasus operations.

Value	Meaning
PF_AllocateComment	Causes the Pegasus routine to return with a RES_ALLOCATE_COMMENT_BUF response when a comment is encountered in the image
PF_ConvertGray	Converts a color input image to a gray scale DIB.
PF_CreateDibWithMadeColors	When PF_MakeColors is specified, outputs a DIB using the optimal colors.
PF_Dither	Dithers the color-mapped output
PF_EOIFound	Pegasus sets this flag when it encounters a JPEG EOI marker in the file
PF_MakeColors	Set to create an optimal color palette for color output image or an optimal set of gray levels for a gray scale output image (see GraysToMake field for additional information).
PF_NoCrossBlockSmoothing	Set if the decode operation should not smooth edges between blocks (group of pixels). It is recommended to use this flag together with the EnhanceMethod field to enable proprietary image enhancement techniques and improve decoded image quality. Cross-block smoothing should only be enabled when working with overcompressed (more than 10:1) jpeg images with visible artifacts. In this case, the algorithm will perform slightly better than the recommended enhancement techniques with a similar decoding quality.
PF_NoDibPad	Set if Pegasus is not to pad the output DIB to a DWORD boundary
PF_OnlyUseMadeColors	When PF_MakeColors is specified, this flag instructs Pegasus to output only the DIB created using the optimal colors. Otherwise, Pegasus will output a DIB while the optimal colors are being created. This first DIB output will use the colors defined by the PIC_PARM ColorTable if any. Otherwise it will use the colors saved with the image file, if any. Otherwise this first DIB will not be output even though PF_OnlyUseMadeColors is not set.
PF_SwapRB	Set to receive output data in the format R-G-B instead of B-G-R. If PF_YuvOutput is set, then the output U and V samples are swapped.
PF_UsedMMX	Pegasus sets this flag to indicate that Intel processor MMX optimizations were used.
PF_UsedP3	Pegasus sets this flag to indicate that Intel processor P3 optimizations were used.
PF_WidthPadKnown	Set if the padded length of one DIB pixel line has been set by the application. Otherwise the length is computed by Pegasus.
PF_YieldPut	Set if the RES_PUT_DATA_YIELD response is desired.
PF_YuvOutput	Set to receive YUV output formats. Used in conjunction with BI_UYVY, BI_YUY2, BI_YV12, or BI_IYUV

PicFlags2

Value	Meaning
PF2_CompressedYUV	Use this switch for YUY2 or UYVY output if the decompressor is to 'compress' the Y output intensity range to 0-235 and U/V intensity range is 0-240. Otherwise the Y/U/V output intensity ranges are 0-255 unless clipped with PF2_ClippedYUV.
PF2_ClippedYUV	Use this switch for YUY2 or UYVY output if PF2_CompressedYUV is not set and if the decompressor is to clip the Y output intensity range to 0-235 and U/V intensity range is 0-240. Otherwise the Y/U/V output intensity ranges are 0-255. This flag would be used if you knew that the original input to the compressor was compressed YUV, but that this input had been compressed as though it were full-range YUV. Setting this flag then prevents compression error from inadvertently driving decompressed intensities out of the acceptable range for compressed YUV.
PF2_MMXDisable	Set this switch to disable use of Intel processor MMX optimizations (this will also disable P3 optimizations).
PF2_P3OptDisable	Set this switch to disable use of Intel processor P3 optimizations.
PF2_NoYccTransform PF2_RgbJpeg	Pegasus sets this flag (the two names have the same #defined value and therefore exactly the same behavior) during REQ_INIT if the compressed image is a 3‑component, 8-bit per component image that does not have a JFIF marker, and that has an Adobe APP14 marker with a color transform value of 0, or does not have an Adobe APP14 marker but has component IDs 'R', 'G', 'B' indicating that the compressed data is in the RGB colorspace instead of in the more customary YCbCr colorspace. Pegasus sets this flag during REQ_INIT for a 4-component, 8-bit per component image that does not have an Adobe APP14 marker, or that has an Adobe APP14 marker with a color transform value of 0. If this flag is set during REQ_EXEC, then no color conversion will be done. The application can set or clear this flag after REQ_INIT before REQ_EXEC to override the automatic determination of colorspace and force suppression or inclusion of any color conversion.
PF2_SmoothUpsample	Set this switch to use slower but better quality smooth upsampling for chrominance. Only applies to 211 case for 8‑bit output and 16‑bit dithered output and to 411 case for 24‑bit or 32‑bit output.
PF2_RgbaOutput	Set this flag for a four-component compressed image to decompress to RGBA output (ordered B/G/R/A unless PF_SwapRB is set) instead of decompressing to CMYK output.
PF2_AcrobatCmyk	Set this flag to expand CMYK compressed images compatible with Acrobat instead of being compatible with Photoshop. Acrobat complements C/M/Y before applying the YCbCr conversion and otherwise doesn't complement. Photoshop doesn't complement C/M/Y before applying the YCbCr conversion and otherwise complements.

DibSize

Specifies the size of the desired DIB in bits (4, 8, 16, 24 or 32). If DibSize is 0, then it is set by Pegasus to 24 if the input image is not gray scale or 8 if the input image is gray scale. If DibSize is 16, 24 or 32 and the input image is 8bpp gray scale or PF_ConvertGray is set in PicFlags, then Pegasus sets DibSize to 8. If DIBSize is 16 and input image is 12bpp gray scale, then 12 bpp gray is output within 16 bits.

Thumbnail

Specifies the size of the thumbnail to create. This field can be one of the following values:

Value	Meaning
THUMB_NONE	Full image size
THUMB_4	1/4 image size thumbnail
THUMB_16	1/16 image size thumbnail
THUMB_64	1/64 image size thumbnail

NumScansReq

NumScansDone

NumBytesDone

Not used by the OP_S2D opcode and must be set to 0.

GraysToMake

When PF_ConvertGray is set in PicFlags or the input image is gray scale, then the output DIB will be gray scale. In that case, GraysToMake can be used to specify the number of gray levels (0 or 2..256) to create when converting the image to gray scale. A value of 0 defaults to 16 or 236 levels depending on DibSize.

If the output DIB will be gray scale, and if PF_MakeColors is specified and GraysToMake is consistent with DibSize, then GraysToMake is honored by Pegasus.

If the output DIB will be gray scale, and if PF_ConvertGray is not specified or the PIC_PARM Head.biClrUsed field is 0 (no input color/gray table is supplied), and if GraysToMake is consistent with DibSize, then GraysToMake is honored by Pegasus.

PrimClrToMake

If PF_MakeColors is set In PicFlags, and PF_ConvertGray is not set and the input image is a color image, PrimClrToMake specifies the desired number of colors to make in the primary palette [0 or 2..256]. A value of 0 defaults to 236.

SecClrToMake

if PF_MakeColors is set In PicFlags, and PF_ConvertGray is not set and PrimClrToMake is not 0 and the input image is a color image, SecClrToMake specifies the desired number of colors to make in the secondary palette [0 or 2..16]. A value of 0 defaults to 16.

StripSize

Specifies the minimum buffer size needed to hold one strip of output data. This field is output by Pegasus. Each JPEG strip is 8 or 16 image lines. The operation acts on the input data one strip at a time, so at least one complete strip of output data is to the Put queue at a time, except at the end of the image. Thus, this is also the minimum buffer size for the Put queue. If larger, and using Q_REVERSE, the Put queue buffer size must be an integer multiple of StripSize.

WidthPad

Specifies the width of an uncompressed DIB pixel line in bytes. WidthPad takes into account the number of bits needed to represent a pixel and any padding that may be required at the end of each line. WidthPad will be output by Pegasus unless the PF_WidthPadKnown flag is set in PicFlags. If PF_WidthPadKnown is set, then WidthPad must be input by the application. In that case, the operation will expand Head.biWidth bits and will then use WidthPad to advance to the next pixel line. This allows the application to easily expand to a rectangle within the DIB which is aligned on the left edge of a DIB. The application can expand to an arbitrary rectangle within the DIB with some additional complexity. This technique is also used to generate 'raw' image data that contains specific padding or, more frequently, no padding.

LumFactor

If the JPEG image were created by a PICTools/AIMTools operation, then the LumFactor specified when the file was created is returned in this field. See the LumFactor description in the DIB_INPUT: OP_D2S section for additional information.

ChromFactor

If the JPEG image were created by a PICTools/AIMTools operation, then the ChromFactor specified when the file was created is returned in this field. See the ChromFactor description in the DIB_INPUT: OP_D2S section for additional information.

SubSampling

Specifies sub-sampling used to create the input image.

Value	Meaning
SS_111	Cb and Cr weren't sub-sampled
SS_211	Cb and Cr were sub-sampled 2 to 1 horizontally, not vertically
SS_411	Cb and Cr were sub-sampled 2 to 1 vertically and horizontally
SS_211v	Cb and Cr were sub-sampled 2 to 1 vertically, not horizontally

If any other value is returned for SubSampling, the returned value was computed by Pegasus as:

( (H * Y ) << 27 ) | ( ( V * Y ) << 22 ) |

( (H * Cb ) << 17 ) | ( ( V * Cb ) << 12 ) |

( (H * Cr ) << 7 ) | ( ( V * Cr ) << 2 )

where H and V are the sub-sampling factors defined in the JPEG specification.

JpegType

Specifies the type of JPEG file.

Value	Meaning
JT_PIC2	PIC2 format (Els Coded ePIC format)
JT_EXIF	EXIF format JPEG image
JT_RAW	JFIF-compliant JPEG

AppFieldSize

Specifies the size of the buffer pointed to by the AppField field. If the application sets this field to -1 and the image contains APP2 marker data, the Pegasus routine will return to the application with a RES_ALLOCATE_APP2_BUF response. At this time, AppFieldLen field will contain the length of the APP2 marker data in the image. The application can allocate a buffer, set AppField to point to the buffer, and continue Pegasus execution to retrieve all of the data associated with the APP2 marker.

AppFieldLen

When the operation is complete, this field contains the length of APP2 marker data copied to the AppField buffer. When Pegasus returns with a RES_ALLOCATE_APP2_BUF response, this field has the length of the APP2 marker data in the image. The application can allocate a buffer, set AppField to point to the buffer, and continue Pegasus execution to retrieve the data associated with the APP2 marker.

NumOfPages

PageNum

Context

These fields are not used by the OP_S2D opcode and must be set to 0.

DitherType

Used if dithering. 0 = Floyd-Steinberg. (If != 1 on Solaris, it is a fast dither for colormapped output.)

YuvOutputType

BI_UYVY, BI_YUY2, BI_YV12, or BI_IYUV. Ignored unless PF_YuvOutput is set.

ExifThumbnailLen

Length of the buffer pointed to by ExifThumbnail when decompressing the thumbnail from an Exif image file.

ResolutionUnit

ResolutionUnit is 0 if XResolution/YResolution specifies aspect ratio, otherwise 1 is inches and 2 is centimeters.

Xresolution

Horizontal pixels / resolution unit or numerator of aspect ratio.

Yresolution

Vertical pixels / resolution unit or denominator of aspect ratio.

Brightness

Contrast

ContrastOfs

Specifies the amount to increase or decrease the decompressed output image's brightness, contrast and contrast offset (as specified below) during decompression. Acceptable values are from -4095 to 4095. A value of 0 means the image is not changed for that parameter. The adjusted pixel luminance (L_out) is related to the unadjusted pixel luminance (L_in) as:

L_out = Brightness/16 + tan(p/2*(Contrast+4096)/8192)*(L_in-ContrastOfs/16)

for 8-bit intensity samples (0-255). For 12-bit intensity samples, Brightness and ContrastOfs aren't divided by 16. The output L_out values are clamped to the appropriate output range. If you graph this equation with L_in as the horizontal axis and L_out as the vertical axis, changes to Contrast without changing Brightness or ContrastOfs have the effect of rotating the graphed line around the point (ContrastOfs, Brightness). Brightness raises (+) or lowers(-) the graphed line without rotating it. ContrastOfs shifts the graphed line right (+) or left (-) without rotating it.

EnhanceMethod

If PF_NoCrossBlockSmoothing is not set in PicFlags, then this field further specifies which of the Accusoft proprietary enhancement algorithms to apply when decompressing sequential JPEG images (opcodes OP_S2D and OP_SE2D). Either set this field to 0 to select Method 0 or set it to a value that is the bitwise 'OR' of the numeric values of the individual methods other than Method 0 to select those methods; any combination of methods may be chosen. When decompressing progressive JPEG images (opcode OP_P2D) this field is ignored and the default Method 0 is used.

Method	Meaning
EM_CrossBlockSmoothing	Clean up low frequency contouring and artifacts (default)
EM_ReduceContouring	Clean up only low frequency contouring
EM_ReduceArtifacts	Clean up only low frequency artifacts
EM_ReduceBlockEdgeArtifacts	Clean up block edge artifacts

Planar1Offset

Planar2Offset

Set to 0 if 'simple' decompression to planar YUV. Otherwise (defining 'not simple') these mean the output image is re-interleaving lines or compositing the decompressed image into a larger image subrectangle. For planar YUV the Get queue must hold the entire image.

If Q_Reverse is not set:

if Put.Front is offset N samples from the actual start of the entire image Y plane, set Planar1Offset to <size Y plane> +N/2 where <size Y plane> is <width> * <height> for the <width> and <height> of the entire image. Set Planar2Offset to Planar1Offset + <size Y plane>/4. Thus Planar1/2Offset are the offsets from Put.Front of the U or V samples corresponding to the Y sample pointed to by Put.Front.

Else Error if Q_Reverse is set.