PICTools Programmer's Reference
UTL_STRUC
Operation Structures > UTL_STRUC

UTL_STRUC: OP_UTL

The UTL_STRUC structure contains the parameters for the OP_UTL opcode used for color reduction image operations.

 
Copy Code 
typedef struct {
   DWORD                   Reserved0;
   BYTE PICHUGE *          ptr1;
   BYTE PICHUGE *          ptr2;
   BYTE PICHUGE *          ptr3;
   BYTE PICHUGE *          Reserved4;
   BYTE PICHUGE *          Reserved5;
   BYTE PICHUGE *          Reserved6;
   BYTE PICHUGE *          Reserved7;
   BYTE PICHUGE *          Reserved8;
   PICFLAGS                PicFlags;
   PICFLAGS                PicFlags2;
   DWORD                   AllocType;
   DWORD                   Subcode;
   DWORD                   HistogramSize;
   BITMAPINFOHEADER        BiOut;
   DWORD                   RetainPalette;
   DWORD                   Orient;
   DWORD                   OutBpp;
   DWORD                   NumColors;
   DWORD                   OutWidthPad;
   DWORD                   TransparentColorIndex;
   DWORD                   ReduceError;
   BYTE                    BackgroundColorIndex;
   BYTE                    DitherType;
   WORD                    Expansion4c;
   DWORD                   Expansion5;
   DWORD                   Expansion6;
   DWORD                   Expansion7;
   DWORD                   Expansion8;
   DWORD                   Expansion9;
   DWORD                   Expansion10;
} UTL_STRUC;

Fields:

Name Description

Reserved0

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

ptr1

For subcodes 1 and 2, ptr1 points to a buffer for a color histogram.  The color histogram is output by subcode 1 and input to subcode 2.

ptr2

For subcodes 3 and 4, ptr2 points to a buffer for a color map.  The color map is output by subcode 3 and input to subcode 4.

ptr3

For subcodes 4 and 8, ptr3 points to a color table consisting of an array of u.UTL.NumColors RGBQUAD elements.

Reserved4

Reserved5

Reserved6

Reserved7

Reserved8

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

PicFlags

Value

Meaning

PF_IncludeBMPHead

If set, then the input and/or output data will begin with a BITMAPINFOHEADER, followed by a color map if applicable, followed by the DIB bits. If clear, then the input and/or output data will be the DIB bits only.

PF_ConvertGray

Set for subcode 4 to convert the input DIB to gray levels.

PF_Dither

Set for subcodes 4, 7 and 8 if dithering is desired in the output DIB.

PicFlags2

Value

Meaning

PF2_ColorMap444

Set for subcodes 3, 4, 7, and 8 to indicate a RGB444 color map is used.

PF2_ShowReduceError

Set for subcodes 4, 7, and 8 to compute and obtain the color reduction error. Applies only to 8 bpp or less color-mapped images.

PF2_ApplyReduceErrorThreshold

Set for subcodes 4, 7, and 8 to apply an error reduce threshold. The threshold is specified in u.UTL.ReduceError. Applies only to 8 bpp or less color-mapped images.

AllocType

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

Subcode

Set according to the color reduction utility function desired:

  • Subcode 0: Increase DIB pixel depth
  • Subcode 1: Add color histogram data from a DIB
  • Subcode 2: Create an optimal palette from color histogram data
  • Subcode 3: Create a color map from a palette
  • Subcode 4: Palettize a DIB to a palette or convert a DIB to gray scale
  • Subcode 5: Not used
  • Subcode 6: Convert a color palette to a gray scale palette
  • Subcode 7: Palettize a DIB to its optimal palette
  • Subcode 8: Palettize a DIB to an arbitrary palette

HistogramSize

For subcodes 1 and 2, this is set to the size, in WORDS of the histogram buffer pointed to by ptr1.  This value is always 32,768.

BiOut

For subcodes 0, 4, 7 and 8, this is the output BITMAPINFOHEADER which describes the output DIB.  It is output whether or not PF_IncludeBMPHead is set in u.UTL.PicFlags.

RetainPalette

For subcode 0, this may be set to 1 for a 24 bits-per-pixel output image when PF_IncludeBMPHead is set if the input color table should be output as part of the BMP image, even though the color table is not necessary then.

Orient

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

OutBpp

For subcodes 0, 4, 7 and 8, this is the output DIB bit depth.  It may be 1, 4 or 8 bits per pixel.  It may also be 24 bits per pixel for subcode 0.

NumColors

On input, for subcodes 2, 4 and 7, this is the number of colors desired in the output palette (and output DIB for subcodes 4 and 7).  On output from subcodes 2 and 7, this is set to the number of colors actually present in the optimum output palette, if different from the desired number of colors.

OutWidthPad

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

TransparentColorIndex

For subcode 1, if PF_ApplyTransparency is set, this index is ignored when constructing the color histogram. 
For subcodes  4, 7, and 8, if PF_ApplyTransparency is set, input transparent pixels are mapped to the last palette entry.

ReduceError

For subcodes 4, 7, and 8, if PF2_ApplyReduceErrorThreshold is set, this specifies the error threshold above which the operation will be aborted. Applies only to 8 bpp or less color-mapped images.

BackgroundColorIndex    

For subcodes 4, 7, and 8, and for images of 8 bpp or less, for input, specifies the background palette index. On output, it is returned as the re-mapped index in the output palette.

DitherType

Set to 0 for default dither; 1 for faster, less accurate dithering.

Expansion4c

Expansion5

Expansion6

Expansion7

Expansion8

Expansion9

Expansion10

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

 

 

©2022. Accusoft Corporation. All Rights Reserved.

Send Feedback