PICTools Programmer's Reference
DIB_INPUT
Operation Structures > DIB_INPUT

DIB_INPUT: OP_D2J, OP_D2S, OP_D2SE, OP_D2SEPLUS

The DIB_INPUT structure contains the parameters for compressing a DIB to a sequential JPEG image using the OP_D2S group of opcodes.  The possible input DIB formats include BI_RGB, BI_CMYK, BI_GR12, B_RGB555, BI_RGB565, BI_RGBA, BI_YUY2, BI_UYVY, BI_YV12, and BI_IYUV.

 
Copy Code 
typedef struct {
   DWORD                    Reserved0;
   BYTE PICHUGE*            AppField;
   BYTE PICHUGE*            QTable;
   SCAN_PARM PICHUGE*       ScanParms;
   BYTE PICHUGE *           ExifThumbnail;
   BYTE PICHUGE*            Reserved5;
   BYTE PICHUGE*            Reserved6;
   BYTE PICHUGE*            Reserved7;
   BYTE PICHUGE*            Reserved8;
   PICFLAGS                 PicFlags;
   PICFLAGS                 PicFlags2;
   LONG                     PrimClrToMake;
   LONG                     SecClrToMake;
   LONG                     LumFactor;
   LONG                     ChromFactor;
   SUBSAMPLING              SubSampling;
   JPEG_TYPE                JpegType;
   LONG                     AppFieldSize;
   LONG                     AppFieldLen;
   LONG                     NumOfPages;
   LONG                     PageNum;
   LONG                     Context;
   LONG                     StripSize;
   LONG                     WidthPad;
   LONG                     NumProgScans;
   LONG                     ExifAppsToKeep;
   DWORD                    ExifThumbnailLen;
   THUMBNAIL                ExifThumbnailToMake
   LONG                     AppsToOmit;
   LONG                     RightShift12;
   DWORD                    ResolutionUnit;
   DWORD                    XResolution;
   DWORD                    YResolution;
   LONG                     Brightness;
   LONG                     Contrast;
   LONG                     ContrastOfs;
   LONG                     RestartInterval;
   DWORD                    Planar1Offset;
   DWORD                    Planar2Offset;                                       
} DIB_INPUT;

Fields:

Name Description

Reserved0

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

AppField

Points to a buffer to hold application binary data to be saved as APP2 marker code data in the JPEG image.

QTable

Points to two buffers of 64 bytes each to be used as the luminance and chrominance quantization tables during compression.  If the application supplies these tables, then the LumFactor and ChromFactor fields are not used. If the application sets this field to 0, the operation uses default quantization tables as adjusted by LumFactor and ChromFactor.

ScanParms

This field is not used by the OP_D2S opcode and must be set to 0.

ExifThumbnail

Points to JFIF format thumbnail image for Exif output if desired. Error unless JpegType == JT_EXIF && ExifThumbnailoMake == THUMB_NONE.

Reserved5

Reserved6

Reserved7

Reserved8

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

PicFlags

Flags that control the JPEG compression operation.

Value

Meaning

PF_App1Pal

If PF_MakeColors is set, saves the made colors in the APP1 marker data of the JPEG image.  This allows the optimum colors to be available when the image is expanded even when the output image format is JFIF-compliant (JT_RAW).

PF_IsGray

Set if input image is gray.

PF_MakeColors

Set if optimum colors are to be created based upon the image.  PrimClrToMake and SecClrToMake set the number of colors which are made.

PF_NoDibPad

Set if the input image is not padded to a DWORD boundary.  DIB pixel lines are ordinarily padded so that the number of bytes in a line is an integral number of DWORDs.

PF_OptimizeHuff

Set to create optimized Huffman codes during compression instead of using default Huffman codes.

PF_YieldGet

Set if the RES_GET_DATA_YIELD response is desired.

PF_YieldPut

Set if the RES_PUT_DATA_YIELD response is desired.

PF_WidthPadKnown

Set if the padded length of one DIB line (WidthPad) has been set by the application.  Otherwise the length is computed by Pegasus.

PF_ElsCoder

Use PIC-enhanced entropy coding instead of Huffman coding.

PF_SwapRB

Set if the input data is in the order R-G-B

PF_UseYCbCrForColors

If PF_MakeColors is set, creates a set of optimal YCbCr colors (then translates to RGB) instead of directly creating an optimal set of RGB colors.

PF_WordQtbl

The user-specified quantization table uses 64 16-bit values.

PicFlags2
Value Meaning

PF2_UseResPoke

The opcode will respond with RES_POKE messages if the entire compressed image will not fit in the Put queue and data (Put.RearEnd - Put.FrontEnd) needs to be poked into a position SeekInfo from the start of the output data.

PF2_Cosited

If subsampling is SS_211, use this to get cosited subsampling.

PF2_OmitISOStandardHuffmanTables

Use this switch to use the ISO Standard Huffman tables and leave them out of the file. (Mostly used by MJPEG applications.)

PF2_CompressedYUV

Use this switch for YUY2 or UYVY input if the compressor is to assume the Y intensity range is 0-235 and U/V intensity range is 0-240.  Otherwise these intensity ranges are assumed to be 0-255.

PF2_RgbJpeg/PF2_NoYccTransform

Set this flag to force omitting the color transform to YCbCr from uncompressed input RGB, RGBA, or CMYK before compressing.  Otherwise, the color transform to YCbCr is used.

PF2_AcrobatCmyk

Set this flag to create 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.

PrimClrToMake

Specifies the number of colors to be made for an optimum primary palette [0 or 2..256].  If 0 is specified, then 236 primary colors are made and 16 secondary colors are made.  This field is ignored unless the PF_MakeColors flag is set in PicFlags.

SecClrToMake

Specifies the desired number of colors to be made for an optimum secondary palette [0 or 2..16].  This field is ignored unless the PF_MakeColors flag is set in PicFlags and unless PrimClrToMake is not 0.  Otherwise, if 0 is specified, then no secondary colors are made.

LumFactor

If QTable is NULL, specifies the desired luminance compression factor [0..255].  The luminance compression factor is used to adjust the default luminance quantization table values. When LumFactor is 32, the default luminance quantization table values are used as is.

When LumFactor and ChromFactor are 0, the quality is highest and the compression ratio is virtually non-existent.  When LumFactor and ChromFactor are 255, the quality is lowest and the compression ratio is highest.

ChromFactor

If QTable is NULL, specifies the desired chrominance compression factor [0..255].  The chrominance compression factor is used to adjust the default chrominance quantization table values. When ChromFactor is 32, the default chrominance quantization table values are used as is.

When LumFactor and ChromFactor are 0, the quality is highest and the compression ratio is virtually non-existent.  When LumFactor and ChromFactor are 255, the quality is lowest and the compression ratio is highest.

SubSampling

Specifies the desired sub-sampling. This field, together with Compactor and LumFactor, controls the compression ratio and the compressed image quality.  Note that, in all cases, Y is not sub-sampled.

Value

Meaning

SS_111

Cb and Cr aren't subsampled

SS_211

Cb and Cr are sub-sampled 2 to 1 horizontally, not vertically

SS_411

Cb and Cr are sub-sampled 2 to 1 vertically and horizontally

SS_211v

Cb and Cr are sub-sampled 2 to 1 vertically, not horizontally

JpegType

Specifies the desired type of JPEG file to create.

Value

Meaning

JT_PIC2

PIC2 format (required if ELS-coded)

JT_BMP

Windows BMP with JPEG compression (no longer supported)

JT_RAW

JFIF-compliant JPEG

JT_EXIF

EXIF-compliant JPEG

AppFieldSize

This field is not used by the OP_D2S opcode and must be set to 0.

AppFieldLen

Specifies the length, in bytes, of the data in the buffer pointed to by the AppField field and which is to be saved as APP2 marker code data in the JPEG image.

NumOfPages

PageNum

Context

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

StripSize

Specifies the minimum buffer size needed to hold one strip of input 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 input data should be added to the Get queue at a time, except at the end of the image.  Thus, this is also the minimum buffer size for the Get queue.  If larger and using Q_REVERSE, the Get 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 compress Head.biWidth bits and will then use WidthPad to advance to the next pixel line.  This allows the application to easily compress a rectangle within the DIB which is aligned on the left edge of a DIB.  An arbitrary rectangle within the DIB can be compressed with some additional complexity.

NumProgScans

This field is not used by the OP_D2S opcode and must be set to 0.

ExifAppsToKeep

Bit level control of the application markers to keep when saving as Exif JPEG. Bit 0 on keeps JFIF App0, Bit 1 on keeps PIC App1 marker (not recommended).

ExifThumbnailLen

Used to insert an application provided thumbnail image into an Exif file's thumbnail field. It contains the length of the JFIF thumbnail data pointed to by ExifThumbnail. JpegType must = JT_EXIF and ExifThumbnailToMake must = THUMB_NONE.

ExifThumbnailToMake

To force D2S opcodes to make an Exif Thumbnail from the compressed data, ExifThumbnailToMake must not = THUMB_NONE and JpegType must = JT_EXIF and ExifThumbnailLen must = 0. This forces the use of OP_S2D and OP_D2S to create the thumbnail.

AppsToOmit

This controls which JFIF application markers are omitted from the output image. Bit 0 on causes the omission of the JFIF App0 marker, Bit 1 on omits the PIC App1 marker.

RightShift12

Only used for compressing 2 byte per pixel grayscale data to 12 bit JPEG format. This is how much the data needs to be right-shifted so that the high 4 bits of the word are guaranteed to be 0. It can take values from   0 through 4. For example if the data were left-justified in the word, this parameter would be set to 4.

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 a YUY2 or UYVY input image's brightness, contrast and contrast offset (as specified below) during compression.  Acceptable values are from -4095 to 4095.   A value of 0 means the image is not changed for that parameter.  The adjusted pixel luminance (Lout) is related to the unadjusted pixel luminance (Lin) as:

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

for 8-bit intensity samples (0-255).   For 12-bit intensity samples, Brightness and ContrastOfs aren't divided by 16.  The output Lout values are clamped to an 8-bit or 12-bit range as appropriate.  If you graph this equation with Lin as the horizontal axis and Lout 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. 

RestartInterval

If 0, then no JPEG restart markers are output with the compressed data.  Otherwise, RestartInterval specifies the number of MCUs (minimum coded units) to appear between restart markers.  For SubSampling SS_111, each MCU is 8x8 pixels.  For SS_211, each MCU is 16x8 pixels.  For SS_211v, each MCU is 8x16 pixels.  For SS_411, each MCU is 16x16 pixels.  Each image MCU row is horizontally-padded to an MCU boundary if needed.  For example, to output a restart marker every 16 lines for an image whose SubSampling is SS_211, set RestartInterval to:

RestartMarker = 2 * ( ( Head.biWidth + 15 ) / 16 );

Planar1Offset, Planar2Offset

Set to 0 if 'simple' compression from planar YUV. Otherwise (defining 'not simple') these describe a compressed image that will have de-interlaced lines from the input image or a subrectangle of the input is being compressed. For planar YUV the Get queue must hold the entire image.

If Q_Reverse is not set:

if Get.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 Get.Front of the U or V samples corresponding to the Y sample pointed to by Get.Front.

Else Error if Q_Reverse is set.

 

 

©2022. Accusoft Corporation. All Rights Reserved.

Send Feedback