ZOOM_PARMS 2

ZOOM_PARMS: OP_ZOOM2

The ZOOM_PARMS structure contains the parameters for the OP_ZOOM2 opcode used for changing the dimensions of a DIB, converting a DIB to gray scale or converting a DIB to halftone. With OP_ZOOM2 the ZOOM_PARMS structure is used as follows.

	Copy Code
typedef struct { DWORD Reserved0; BYTE PICHUGE* Reserved1; BYTE PICHUGE* Reserved2; BYTE PICHUGE* Reserved3; BYTE PICHUGE* Reserved4; BYTE PICHUGE* Reserved5; BYTE PICHUGE* Reserved6; BYTE PICHUGE* Reserved7; BYTE PICHUGE* Reserved8; PICFLAGS PicFlags; PICFLAGS PicFlags2; LONG NewWidth; LONG NewHeight; WORD Mode; WORD NewBitCount; void PICFAR* WorkArea; BITMAPINFOHEADER BiOut; DWORD Reserved; REGION RegionOut; } ZOOM_PARMS;

Copy Code

typedef struct {  
   DWORD                    Reserved0;
   BYTE PICHUGE*            Reserved1;
   BYTE PICHUGE*            Reserved2;
   BYTE PICHUGE*            Reserved3;
   BYTE PICHUGE*            Reserved4;
   BYTE PICHUGE*            Reserved5;
   BYTE PICHUGE*            Reserved6;
   BYTE PICHUGE*            Reserved7;
   BYTE PICHUGE*            Reserved8;
   PICFLAGS                 PicFlags;
   PICFLAGS                 PicFlags2;
   LONG                     NewWidth;
   LONG                     NewHeight;
   WORD                     Mode;
   WORD                     NewBitCount;
   void PICFAR*             WorkArea;
   BITMAPINFOHEADER         BiOut;
   DWORD                    Reserved;
   REGION                   RegionOut;
} ZOOM_PARMS;

Fields:

Name

Description

Reserved0

Reserved1

Reserved2

Reserved3

Reserved4

Reserved5

Reserved6

Reserved7

Reserved8

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

PicFlags

Flags that control the zoom operation.

Value	Meaning
PF_FastZoom	Use fast zoom mode.
PF_ConvertGray	Convert image to grayscale.
PF_PreserveBlack	In fast zoom mode with 1-bit input, ensures preservation of all black pixel values. In shrinking a 1-bit input image to a grayscale output image, ensures that black pixel values are not overly diluted.
PF_YieldGet	Set if the RES_GET_DATA_YIELD response is desired.

PicFlags2

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

NewWidth

This field can be used to specify the new image width, although use of the Width field of the output region described by RegionOut field is preferred (REGION or REGION2-see the comments on REGION2 below). If NewWidth is nonzero and the Width field of the output region is zero, then the Width field of the output region is reset to the value of NewWidth. If both NewWidth and the Width field of the output region are nonzero, then they must be equal.

NewHeight

This field can be used to specify the new image height, although use of the Height field of the output region described by RegionOut field is preferred (REGION or REGION2 - see the comments on REGION2 below). If NewHeight is nonzero and the Height of the output region is zero, then the Height field of the output region is reset to the value of abs(NewHeight) and the RF_TopDown bit of RegionOut.Flags is set if NewHeight is negative. If both NewHeight and the Height field of the output region are nonzero, then the Height field of the output region must equal abs(NewHeight) and the RF_TopDown bit of RegionOut.Flags must be set if and only if NewHeight is negative.

Mode

If Mode is 0, then the new image has dimensions new_width (as given by NewWidth or the Width field of the output region) columns by new_height (as given by abs(NewHeight) or the Height field of the output region) lines.

If Mode is nonzero, then the new image has dimensions

Input_width* ( new_width / new_height )

columns (rounded) by

input_height* ( new_width / new_height )

rows (rounded). The REQ_INIT operation returns the new image dimensions in NewWidth and NewHeight, and in BiOut.biWidth and BiOut.biHeight, as well as in the Width and Height fields of the output region.

Both new_width and new_height must be greater than 0 and less than 65536.

NewBitCount

This field can be used to specify the new image bit-depth, although use of the Bpp field of the output region is preferred (REGION or REGION2- see the comments on REGION2 below). If NewBitCount is nonzero and the Bpp field of the output region is zero, then the Bpp field of the output region is reset to the value of NewBitCount. If both NewBitCount and the Bpp field of the output region are nonzero, then they must be equal.

WorkArea

This is reserved.

BiOut

Description of the output image. This component is set by the initial REQ_INIT request. It is recommended that the calling program refer to the output region (REGION or REGION2 - see the comments on REGION2 below) rather than BiOut although both are set. BiOut contains the BITMAPINFOHEADER for the new image. In cases where the new image has a color palette, the palette is stored in the ColorTable element of the PIC_PARM structure. This field is unused for gray-level images using two bytes per pixel. In other cases information is redundant with that provided in RegionOut.

Reserved

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

RegionOut

Description of the output image. This component is set by the initial REQ_INIT request. It is recommended that the calling program refer to RegionOut rather than BiOut although both are set. In cases where the new image has a color palette, the palette is stored in the ColorTable element of the PIC_PARM structure.

The following components of RegionOut may be set before the REQ_INIT operation to specify properties of the output image:

Width
Height
Bpp
PixType
Flags (RF_TopDown, RF_2Byte, RF_Packed).

See REGION for explanation of values of PixType and Flags and their meanings. Values used for OP_ZOOM2 are: PT_CM, PT_GRAY, PT_GRAYM, PT_RGB, PT_RGBA, PT_RGB555, and PT_RGB565. See Default Values below.

The Stride element of RegionOut may be set by the user between the REQ_INIT and REQ_EXEC operations.

The REGION2 structure may be used in place of the REGION for specifying both the input and output rectangles. To do this, recast the addresses of both the RegionIn element of the PIC_PARM structure and the RegionOut element of the ZOOM_PARMS structure as type REGION2* and set the appropriate fields of the corresponding REGION2. The ParmVerMinor field of the PIC_PARM structure should be set to a value not less than 4.

Grayscale Conversion

The image is converted to gray-level if the PF_ConvertGray flag is set, or if the output pixel type is PT_GRAY or PT_GRAYM. Gray-level conversion is also forced:

When the output image is colormapped (pixel type PT_CM) and the input image is not;
When the output image is colormapped with fewer bits per pixel than the input image;
When the input image is 1 bit per pixel and the output image is larger in size than the input.

Halftoning

The image is halftoned (depicted with black and white dots of various sizes) if the input bit-depth is greater than 1 and the output bit-depth is 1. See also OP_BINARIZE for more flexible halftoning operations.

Signed Pixel Values

Signed pixel values may be used for either input or output with the PT_GRAY and PT_GRAYM pixel types.

YUYV

DIBs in YUYV format can be increased or decreased in size; however when the input is YUYV, the output must be YUYV, and vice-versa. See also the note below on fast mode. With YUYV, both input and output widths must be even. In Mode 0, an odd output width results in an error condition. In Mode 1, the output width is rounded to the nearest even value. In addition, when zooming a cropped YUYV image, CropXoffis rounded down to the nearest even value.

Fast Mode

The image is resized using fast mode (resampling) if the PF_FastZoom flag is set or in the following situations:

The input and output bit-depths are both 1;
The input bit depth is 1 and the output width or height is larger than the original;
Input and output images are both colormapped, and the output image has no fewer bits per pixel than the input image;
Input and output images are both gray-level with more than eight bits of precision per sample.
Input and output images are YUYV and either the height or width is increased.

Cropping

Two modes of cropping are available, triggered by the F_InputCrop (or F_Crop) and F_OutputCrop flags of the Flags field of the PIC_PARM structure.

If F_InputCrop is set, then the image is cropped before zooming. The cropping window is specified by the IOCropXoff, IOCropYoff, IOCropWidth, and IOCropHeight parameters of the PIC_PARM structure. The result of this operation is identical to separately cropping the input image, followed by a zoom operation. Values of IOCropXoff or IOCropYoff exceeding the image dimensions result in an error. Zero values of IOCropWidth or IOCropHeight result in an error. Values of IOCropWidth or IOCropHeight exceeding the image dimensions are truncated to the image dimensions.

Alternatively, F_Crop may be set and the cropping window is specified by the CropXoff, CropYoff, CropWidth, and CropHeight parameters of the PIC_PARM structure. This yields results identical to the use of F_InputCrop, provided the 16-bit depth of CropXoff, etc. is not exceeded. However, for OP_ZOOM2 and other opcodes that support it (see opcode list in the F_InputCrop description, in the PIC_PARM section), the use of F_InputCrop is recommended over F_Crop. Values of CropXoff or CropYoff exceeding the image dimensions result in an error. Zero values of CropWidth or CropHeight result in an error. Values of CropWidth or CropHeight exceeding the image dimensions are truncated to the image dimensions.

If F_OutputCrop is set, then the image is cropped after zooming. The cropping window is specified by the IOCropXoff, IOCropYoff, IOCropWidth, and IOCropHeight parameters of the PIC_PARM structure. Note that these are specified relative to the zoomed image coordinates. The result of this operation is identical to zooming the image, followed by a separate cropping operation.

Output cropping is recommended for tiling the zoomed image.

For output cropping, values of IOCropXoff or IOCropYoff exceeding the image dimensions result in an error. Zero values of IOCropWidth or IOCropHeight result in an error. Values of IOCropWidth or IOCropHeight exceeding the image dimensions are truncated to the image dimensions.

At most one of F_InputCrop, F_OutputCrop, or F_Crop may be set in any single zoom operation.

The input region and output region dimensions are calculated according to the specified cropping parameters. The CropOutputXoff, CropOutputYoff, CropOutputWidth, and CropOutputHeight parameters may be set between the REQ_INIT and REQ_EXEC phases. Note that the overall image dimensions are calculated in the REQ_INIT phase.

For a YUYV image, CropXoff, CropOutputXoff, CropWidth, and CropOutputWidth must be even-valued.

Default Values

The Bpp field of the output region, the PixType field of the output region, the output region width, and/or the output region height take default values if set to zero before the REQ_INIT operation. These default values are determined as follows:

If the PixType field of the output region is set to zero, its value is determined from the value of the Bpp field of the output region and the PF_ConvertGray value thus:

PT_CM if 1< output Bpp <=8 and PF_ConvertGray is not set;
PT_GRAY if PF_ConvertGray is set or 8< output Bpp <=16;
PT_RGB if output Bpp=24;
PT_RGBA otherwise.

If the Bpp field of the output region is set to zero, its value is determined from the value of the PixType field of the output region thus:

8 if the output PixType=PT_CM or the output PixType=PT_GRAY;
15 if the output PixType=PT_RGB555;
16 if the output PixType=PT_RGB565 or the output PixType=PT_GRAYM;
24 if the output PixType=PT_RGB;
32 if the output PixType=PT_RGBA.

If the output Bpp and the output PixType are both set to zero, their values are determined thus:

The output Bpp=1 and the output PixType=PT_CM if the input image is 1 bit per pixel;
The output Bpp=8 and the output PixType=PT_GRAY if PF_ConvertGray is set;
The output Bpp=16 and the output PixType=PT_YUYV if the input PixType equals PT_YUYV;
The output Bpp=24 and the input PixType=PT_RGB otherwise.

If the output width or height is set to zero, their values are set to twice the source image width or height, respectively.

Restrictions on both input and output images (after setting default values):

PixType must be one of PT_CM, PT_GRAY, PT_GRAYM, PT_RGB, PT_RGBA, PT_YUYV, PT_RGB555, or PT_RGB565;
Bpp may not take values from 17 to 23, from 25 to 31, or exceeding 32;
Bpp must equal 24 when PixType=PT_RGB and vice-versa;
Bpp must equal 32 when PixType=PT_RGBA and vice-versa;
Bpp must equal 15 or 16 when PixType=PT_RGB555;
Bpp must equal 16 when PixType=PT_RGB565 or PixType=PT_YUYV;
Bpp may not exceed 8 when PixType=PT_CM;
Bpp may not exceed 16 when PixType=PT_GRAY;
PixType may equal PT_GRAYM only if 8<Bpp<=16, or if 1<Bpp<=8 and PF_2Byte is set;
Packed pixels (RF_Packed) may be used on both input and output images only for bit-depths of 1 or 4.
Signed pixels (RF_Signed) may be used on both input and output images only pixel types PT_GRAY or PT_GRAYM.

Other restrictions:

The output PixType may equal PT_RGBA only if the input image also has pixel type RGBA;
The output PixType may equal PT_YUYV only if the input image also has pixel type PT_YUYV, and vice-versa;
Minimum input image dimensions are 4x4;
One-bit-per-pixel images must have packed pixels.
RegionOut.Height and RegionOut.Width must be greater than zero for Mode=0 or 1.
For compatibility with earlier versions the RF_Packed flag of RegionOut is set when NewBitCount is nonzero and the output Bpp is zero, or when both NewBitCount and the output Bpp are zero and the input image has bit-depth 1 (forcing the output image also to have bit-depth 1).