J2K_EXTRA, J2K

J2K_EXTRA: OP_J2KE, OP_J2KE3D, OP_J2KERGB, OP_J2KP, OP_J2KP3D, OP_J2KPRGB

This structure must be zeroed and have ExtraSize set to sizeof(J2K_EXTRA) before use. To use this structure set PIC_PARM.opcodeExtraPtr to point to a valid J2K_EXTRA structure. If PIC_PARM.opcodeExtraPtr does not point to a J2K_EXTRA structure no information will be returned via opcodeExtraPtr.

	Copy Code
typedef struct { DWORD ExtraSize; double CaptureResVert; double CaptureResHorz; double DisplayResVert; double DisplayResHorz; } J2K_EXTRA ;

Fields:

Name	Description
ExtraSize	Must be the size of J2K_EXTRA in bytes.
CaptureResVert	Vertical Capture resolution in canvas grid points per meter.
CaptureResHorz	Horizontal Capture resolution in canvas grid points per meter.
DisplayResVert	Vertical Display resolution in canvas grid points per meter.
DisplayResHorz	Horizontal Display resolution in canvas grid points per meter.

J2K_UNION: OP_J2KE, OP_J2KE3D, OP_J2KERGB, OP_J2KP, OP_J2KP3D, OP_J2KPRGB

	Copy Code
typedef struct { DWORD Reserved0; BYTE PICHUGE* UpdatedTiles; BYTE PICHUGE* ColorSpecICCProfileData; BYTE PICHUGE* Reserved3; BYTE PICHUGE* Reserved4; BYTE PICHUGE* Reserved5; BYTE PICHUGE* Reserved6; BYTE PICHUGE* Reserved7; BYTE PICHUGE* Reserved8; PICFLAGS PicFlags; PICFLAGS PicFlags2 * following in reference grid coordinates / DWORD ImageWidth; DWORD ImageHeight; DWORD ImageXOff; DWORD ImageYOff; DWORD StripSize; REGION Region; DWORD NumOtherPartitions; PARTITION PICHUGE OtherPartitions; DWORD PartitionNum; DWORD TileWidth; DWORD TileHeight; DWORD TileXOff; DWORD TileYoff; TILE DftTile; DWORD NumOtherTiles; TILE PICHUGE* OtherTiles; DWORD Rate; THUMBNAIL Thumbnail; DWORD Resolution; DWORD CompFileSize; DWORD NumPartitions; DWORD ExpandLayers; double TargetPSNR; DWORD ExpandResolution; DWORD SliceOff; DWORD JPEG2000FileFormat; DWORD JPEG2000Profile; BYTE ColorSpecMethod; SBYTE ColorSpecPrecedence; BYTE ColorSpecApproximation; BYTE ColorSpecEnumeratedColorSpace; DWORD ColorSpecICCProfileLen; DWORD CompFileSizeHigh; } J2K_UNION;

Copy Code

typedef struct {

   DWORD                   Reserved0;
   BYTE PICHUGE*           UpdatedTiles;
   BYTE PICHUGE*           ColorSpecICCProfileData;
   BYTE PICHUGE*           Reserved3;
   BYTE PICHUGE*           Reserved4;
   BYTE PICHUGE*           Reserved5;
   BYTE PICHUGE*           Reserved6;
   BYTE PICHUGE*           Reserved7;
   BYTE PICHUGE*           Reserved8; 
   PICFLAGS                PicFlags;
   PICFLAGS                PicFlags2
   * following in reference grid coordinates */
   DWORD                   ImageWidth;
   DWORD                   ImageHeight;
   DWORD                   ImageXOff;
   DWORD                   ImageYOff;
   DWORD                   StripSize;
   REGION                  Region;
   DWORD                   NumOtherPartitions;
   PARTITION PICHUGE*      OtherPartitions;
   DWORD                   PartitionNum;
   DWORD                   TileWidth;
   DWORD                   TileHeight;
   DWORD                   TileXOff;  
   DWORD                   TileYoff;
   TILE                    DftTile;    
   DWORD                   NumOtherTiles;
   TILE PICHUGE*           OtherTiles;
   DWORD                   Rate;          
   THUMBNAIL               Thumbnail;
   DWORD                   Resolution;
   DWORD                   CompFileSize;
   DWORD                   NumPartitions;
   DWORD                   ExpandLayers;
   double                  TargetPSNR;
   DWORD                   ExpandResolution;
   DWORD                   SliceOff;
   DWORD                   JPEG2000FileFormat;
   DWORD                   JPEG2000Profile;
   BYTE                    ColorSpecMethod;
   SBYTE                   ColorSpecPrecedence;
   BYTE                    ColorSpecApproximation;
   BYTE                    ColorSpecEnumeratedColorSpace;
   DWORD                   ColorSpecICCProfileLen;
   DWORD                   CompFileSizeHigh;

 } J2K_UNION;

Fields:

Name

Description

Reserved 0

Must be 0

UpdatedTiles

Ordinarily this is set by OP_JPIPCLIENT or OP_RIDP2. UpdatedTiles is a bitmap of updated 64x64 pixel subrectangles. All subrectangles denoted by a '1' bit are decompressed. If UpdatedTiles <> 0, then full image size output buffers are required. UpdatedTiles are disallowed in reduced-memory mode of the decompressor. For an image width W, the UpdatedTiles bit corresponding to pixel (x, y) is:

Copy Code

intbitsperrow = ( W + 63 ) / 64;

intyofs = y / 64;

intxyofs = ( x / 64 ) + ( bitsperrow * yofs );

intxybyteofs = xyofs / 8;

intxybitofs = 1 << ( xyofs % 8 );

if( UpdatedTiles[xybyteofs] & xybitofs ) != 0 );

// bit is set

ColorSpecICCProfileData

Pointer to a valid ICC Profile.

Reserved3

Reserved4

Reserved5

Reserved6

Reserved7

Reserved8

Must be NULL.

PICFlags

Value	Meaning
PF_YieldPut	(OP_J2KE) Set if RES_PUT_DATA_YIELD response is desired for example for progress reporting during image decompression.
PF_YieldGet	(OP_J2KP) Set if RES_GET_DATA_YIELD response is desired for example for progress reporting during image compression.

PICFlags2

Value	Meaning
PF2_SkipJP2Header	(OP_J2KP, OP_J2KE) If set with OP_J2KP, the Put buffer contains the raw JPEG2000 codestream, without the JP2 or JPX file header. Not recommended. If raw JPEG2000 codestream, without file header is encountered OP_J2KE sets this flag.
PF2_ForceLossless	(OP_J2KP only) Compress the image losslessly, using the reversible color-space and wavelet transforms. Overrides Rate, CompFileSize, TileCompTransform, and WaveletTransform.
PF2_KeepColorTable	For Color Mapped files only, when RF_CM2RGB is specified, optionally keep the color table with the compressed image returned by OP_J2KP or return the color table along with the decompressed image returned by OP_J2KE. This option is redundant when a Color Mapped image and RF_CM2RGB is not specified. This option is ignored if PF2_SkipJP2Header is set in OP_J2KP.
PF2_J2K_TCTNone_RGB	(OP_J2KE only) Return interleaved 24-bit RGB, given a J2K file with 3 unsigned 8-bpp components and no reversible color transform.
PF2_SkipUpsampling	(OP_J2KE only) Don't upsample the image; leave components downsampled.
PF2_AlternateRateDistortion	(OP_J2KP only) not implemented.
PF2_Use32BitPrecision	Process samples during compression and decompression with no more than 8 bits per sample precision using a full 32-bits of precision instead of 16-bits of precision. Performance is slower when this flag is specified, but compression/decompression is very slightly more accurate for lossy compression.
PF2_InsertTLMMarker	(OP_J2KP only) Insert TLM marker, adding J2K header data that is an array of all tile part lengths.
PF2_InsertPPMMarker	(OP_J2KP only) Insert PPM marker facilitating random-access to improve JPIP server stateless performance.
PF2_EarlyOutRateControl	(OP_J2KP only) If set, compression is faster for more compression than for less compression but for high-gray the compressor may not hit the desired rate as closely for some images at highest quality settings.
PF2_FavorSpeed	(OP_J2KP only) Use fastest coding mode for encoding; files created using this flag will also decode faster. Note that when this flag is set, lossless encoded files may become slightly larger and lossy rate-controlled encoded files may decode to slightly lower quality. Can be combined with PF2_EarlyOutRateControl for best performance.
PF2_UseResSeek	(Win32/x64) Allow RES_SEEK events allowing seeking in the input. When Thumbnail, ExpandResolution, or Resolution are set or when cropping, this allows expanding without reading all data in the input file. In the reduced-memory mode of OP_J2KE, this flag is used to choose between a mode that requires seeking in the input and one that operates without any seeks. If the compressed image contains more than one tile, the reduced-memory mode requires that this flag be set and seeking in the input be allowed; otherwise, this flag should be clear for best reduced-memory mode performance. In the reduced-memory mode of OP_J2KP when the application requests that more than one tile be created, this flag must be set and seeking must be allowed in the compressed output stream.
PF2_MMXDisable	Set to disable MMX and later optimizations.
PF2_P2AndP3OptDisable	Set to disable P2, P3 and later optimizations.
PF2_P3OptDisable	If the CPU supports SSE instructions, but the O/S doesn't support SSE instructions, then you must set PF2_P3OptDisable or the CPU will fault.
PF2_P4OptDisable	If the CPU supports SSE2 instructions, but the O/S doesn't support SSE2 instructions, then you must set PF2_P4OptDisable or the CPU will fault.
PF2_ARMAsmDisable	Set to disable user of ARM processor optimizations.
PF2_ARMNeonDisable	Set to disable user of ARM advanced SIMD (NEON) processor optimizations.
PF2_3D_Slices	(J2K volumetric only) Set to instruct opcode to encode input partitions as 3-D slices (one slice per partition) instead of as 2-D components. Returned by opcode to indicate that JPEG2000 image is a 3-D slice encoding and a slice will be returned in each partition.
PF2_ OmitPICMetaData	(OP_J2KP only) Set to suppress inserting Accusoft informational metadata (UUID box) in the output image. It is recommended that this flag not be set.
PF2_ Reduced-MemoryMode	Set to select the reduced-memory mode of operation

The following four elements describe the size and position of the image on the reference grid or canvas. JPEG 2000 allows the upper-left corner to be assigned an arbitrary nonnegative position on a background reference grid. The positions of the other three corners are then constrained by this corner's position and the image dimensions.

ImageWidth

This is the width of the image in pixels.

ImageHeight

This is the height of the image in pixels

ImageXOff

X-position of the image upper-left corner on the JPEG 2000 reference grid. A value of 0 is recommended unless there are specific reasons to do otherwise. The value must be nonnegative.

ImageYOff

Y-position of the image upper-left corner on the JPEG 2000 reference grid. A value of 0 is recommended unless there are specific reasons to do otherwise. The value must be nonnegative

StripSize

This is the minimum size of the buffer to hold data in the first partition. For OP_J2KP, this is the minimum size of the Get Buffer. For OP_J2KE, this is the minimum size of the Put buffer. This is provided to the caller on return from the REQ_INIT phase.

Region

This is the region for the first partition. See Region below. For images with Width, Height, or Stride too large to fit in REGION, REGION2 should be used (see the discussion of the REGION2 structure) and ParmVerMinor must be at least 4.

The following three elements describe the partition structure for the uncompressed/decompressed image data.

NumOtherPartitions

The number of OtherPartitions when there is more than one. This field is ignored when OtherPartitions is NULL. The PicParm.u.J2K.StripSize, PicParm.u.J2K.Region, and PicParm.Get or PicParm.Put queues specify the first partition's components explicitly, and this field specifies all other partitions' components. For OP_J2KP, the maximum allowed value for this field is 16383, because the JPEG2000 standard allows a maximum of 16384 components. For OP_J2KE, if the actual number of partitions required to decode the image is less than the number provided by the app, then the value of this field and the extraneous partitions are ignored and just the required number of partitions are decoded and returned. If the application provides fewer partitions than are required by the image, then just the partitions provided are decoded and returned.

OtherPartitions

This is a pointer to an array of NumOtherPartition partitions, one for each partition after the first, making up the image. If this field is NULL, then only one partition is encoded or decoded. See Partition below.

PartitionNum

This is the number designating which partition is the one to be used whenever a response code RES_GET_NEED_DATA or RES_PUT_NEED_SPACE is returned to the application. If the value is 0, for the first partition, then the PicParm.Get or PicParm.Put queue is being used along with the u.J2K.Region information. Otherwise the value indicates that the Get, Put, and Region structures in the designated partition are to be used for buffer manipulation etc.

The following four elements describe the size and position of the tile grid. This grid can be positioned arbitrarily with respect to both the image and the reference grid.

TileWidth

This is the width of the tile. If 0 (recommended in most cases) then the tile width = ImageWidth

TileHeight

This is the height of the tile. If 0 (recommended in most cases) then the tile height = ImageHeight

TileXOff

X-position of the upper-left corner of the upper-leftmost tile on the JPEG 2000 reference grid. A value of 0 is recommended unless there are specific reasons to do otherwise. The value must be nonnegative and it is constrained to be greater than ImageXOff - TileWidth, but no greater than ImageXOff

TileYOff

Y-position of the upper-left corner of the upper-leftmost tile on the JPEG 2000 reference grid. A value of 0 is recommended unless there are specific reasons to do otherwise. The value must be nonnegative and it is constrained to be greater than ImageYOff - TileHeight, but no greater than ImageYOff..

DftTile

Compression settings for all tiles. When implemented, exceptions for individual tiles can be specified in the OtherTiles array. See Tile.

NumOtherTiles

Not implemented. The number of tiles in the OtherTiles array.

OtherTiles

Not implemented. An array of special compression settings for particular tiles. These settings allow the u.J2K.DftTile settings to be overridden for particular tiles.

Rate

(OP_J2KP) The number of thousandths of a bit per pixel in the compressed image - used to control degree of compression; overrides custom compression settings if set. If set to 0 and CompFileSize and TargetPSNR are 0, then the compressed file size is not arbitrarily limited in size but will depend on the compressibility of the image and on the other compression settings.

Thumbnail

(OP_J2KE) power of 2 by which to scale down size. Allows for faster decompression to a smaller image size and requires less compressed image data depending on the progression ordering.

Resolution

(OP_J2KE) Reserved. Current behavior is that a full-size image is returned but the Resolution number of highest-detail bitslice layers of the image are skipped resulting in a fuzzier image, but requiring less compressed image data depending on the progression ordering. Provides the same functionality as ExpandLayers, and is overridden by ExpandLayers if ExpandLayers is nonzero; therefore, use ExpandLayers instead of this field.

CompFileSize

(OP_J2KP) Desired compressed file size in bytes; overrides Rate or custom compression settings if set. If 0 and TargetPSNR is 0, then the Rate field is used to determine compression size. If Rate is also 0, then the compressed file size is not arbitrarily limited in size but will depend on the compressibility of the image and on the other compression settings.

NumPartitions

(OP_J2KE) After RES_DONE is returned from REQ_INIT, NumPartitions minus one is the number of OtherPartitions required to decompress all image components. If NumOtherPartitions < NumPartitions - 1, then the application could decompress all components by calling REQ_TERM to terminate the current OP_J2KE operation and could then start a new OP_J2KE operation on the same image after reallocating the OtherPartitions array and setting NumOtherPartitions. If REQ_EXEC is called and NumOtherPartitions < NumPartitions - 1, then the extra components aren't decompressed.

ExpandLayers

(OP_J2KE) A full-size image is returned but the ExpandLayers number of highest-detail bitslice layers of the image are skipped resulting in a fuzzier image, but requiring less compressed image data depending on the progression ordering.

TargetPSNR

(OP_J2KP) Set this to the desired compressed image quality as measured by Peak-Signal-to-Noise-Ratio. Overrides Rate and CompFileSize, if set. If 0, then either the Rate or CompFileSize is used to determine compression size.

ExpandResolution

(OP_J2KE) A full-size image is returned but the ExpandResolution number of highest-detail wavelet decomposition levels of the image are skipped resulting in a fuzzier image, but requiring less compressed image data depending on the progression ordering.

SliceOff

(J2K volumetric expand only) Set this to the offset of the first slice to expand. The number of slices to expand, starting from this offset, is determined by the number of partitions provided to the opcode.

JPEG2000FileFormat

This field reports the JPEG2000 file format of the input JPEG2000 image. It is informational only and is returned by REQ_INIT.

Value	Meaning
JPEG2000FileFormat_J2K	Input is a JPEG2000 raw codestream image.
JPEG2000FileFormat_JP2	Input is a JPEG2000 JP2 file format image.
JPEG2000FileFormat_JPX	Input is a JPEG2000 JPX file format image.

JPEG2000Profile

This field reports the JPEG2000 profile as determined from indicators in the JPEG2000 image. It is informational only and is returned by REQ_INIT for the expand opcodes. It can be set before REQ_INIT for the pack opcodes when creating a JPEG2000 file. See the JPEG2000 ISO standard for more information about these profiles.

Value	Meaning
JPEG2000Profile_None	No profile - no restrictions (Part-1)
JPEG2000Profile_0	Profile-0 - most restrictive (Part-1)
JPEG2000Profile_1	Profile-1 - some restrictions (Part-1)
JPEG2000Profile_2	Same as JPEG2000Profile_None
JPEG2000Profile_Part2_Full	Requires full capabilities of JPEG2000 Part-2
JPEG2000Profile_Part2_JPXBaseline	Conforms to JPEG2000 JPX baseline (Part-2)

ColorSpecEnumeratedColorSpace

This field reports the Enumerated Color Space if ColorSpecMethod == J2K_COLOR_SPEC_METHOD_ECS. It is returned during REQ_INIT for the expand opcodes and is not used for the pack opcodes.

Value	Meaning
J2K_COLOR_SPEC_ECS_RGB	sRGB images as defined by IEC 61966-2-1 and ISO/IEC 15444-1:2004.
J2K_COLOR_SPEC_ECS_GREYSCALE	Greyscale images as defined by IEC 61966-2-1 and ISO/IEC 15444-1:2004.
J2K_COLOR_SPEC_ECS_YCC	sYCC images as defined by IEC 61966-2-1 Amd. 1 and ISO/IEC 15444-1:2004.
0	Other.

ColorSpecMethod

This field reports the JPEG2000 Color Specification Method as determined from the Color Specification Box in the JP2 Header box. It is returned by REQ_INIT for the expand opcodes. It can be set, only to J2K_COLOR_SPEC_METHOD_ICP, for the pack opcodes when creating a JPEG2000 file.

Value	Meaning
J2K_COLOR_SPEC_METHOD_ECS	Enumerated Color Space, The color space can be found in the ColorSpecEnumeratedColorSpace field.
J2K_COLOR_SPEC_METHOD_ICP	ICC Profile Color Space. The ICC Profile can be found in the ColorSpecICCProfileData field. If this value is set during REQ_INIT, for a pack opcode, then ColorSpecICCProfileData must be non-NULL and ColorSpecICCProfileLen should be the length, in bytes, of the profile pointed to by ColorSpecICCProfileData.

ColorSpecPrecedence

Reserved. Must be 0.

ColorSpecApproximation

Reserved. Must be 0.

ColorSpecICCProfileLen

The length in bytes of the ICC Profile in ColorSpecICCProfileData.

CompFileSizeHigh

(OP_J2KP) Upper 32 bits of the desired compressed file size in bytes; appended to the value in CompFileSize to create a 64 bit value when needed for extremely large images. Be sure to set to zero when the compressed file size fits in CompFileSize or when CompFileSize is not being specified.