OP_MDCA2D

OP_MDCA2D: Convert a MO:DCA File to a DIB

General Notes

The purpose of OP_MDCA2D is to convert Mixed Object Document Content Architecture (MO:DCA) files to DIBs. The MO:DCA standard includes many different objects but this opcode only supports Image Object Content Architecture (IOCA) and Presentation Text Object Content Architecture (PTOCA) objects. This opcode also supports the conversion of CALS1, IOCA, and C4 images not in MO:DCA files to DIBs.

The overall processing flow for this opcode is as follows:

The client application allocates a Get queue buffer. This buffer can be either large enough to contain the entire input file or only large enough for a portion of the file, in which case the opcode will support streaming input. The client signals to the opcode that the entire file has been read by setting Q_EOF in Get.QFlags.
The client application specifies the page to render by setting ImageNumber. The opcode parses the data from the input file into internal data structures, ensuring that it can render all of the objects on the selected page, sets the PageXRes, PageYRes, PageWidth, PageHeight, and PageResUnits fields to initial values based on the respective values from the file and returns RES_DONE to the client. The client may now deallocate the Get queue buffer. When processing the Get queue the opcode may encounter an Overlay that is external to the file being processed. If this happens it will return RES_NEED_EXTERNAL_OVERLAY with the resource name in ExternalOverlayName, as an ASCIIZ string, of the external resource library that contains the Overlay according to the MO:DCA file. The user should then set ExternalOverlay and ExternalOverlayLength to a buffer into which the entire external resource library has been read.
At this point the client can specify the desired output size of the image, if different from the values from the MO:DCA file, by setting OutHeight and OutWidth or specifying an output resolution using OutXRes, OutYRes, and OutResUnits. This allows you to smoothly render to a smaller or larger size and resolution if desired. Otherwise these values are set from the input file.
At this point the client can allocate space for the Put queue. Streaming output is supported, so either enough space for the entire output image can be allocated, or partial space (with a minimum of StripSize) can be allocated. If partial space is allocated, and if Q_REVERSE is set, then the Put queue must be an integral multiple of StripSize. The client application then invokes REQ_EXEC processing.
The opcode returns image data until the complete specified page has been rendered.

Various items will be returned in PicParm.PIC2List depending on the type of file being processed. For MO:DCA files all of the MO:DCA Structured Fields will be returned as P2PktModca packets. If you are processing an IOCA image not in a MO:DCA file then the IOCA Self Defined Fields will be returned as P2PktIoca packets. If you are processing a CALS1 file then the CALS1 headers will be returned as P2PktCals packets. If you are processing a C4 file, the Hollerith header field, if present, will be returned as a P2PktComment packet. See PIC2List Functions for more information.

This opcode uses platform specific routines that are not available on Windows 95/98/ME.

Output DIB from MO:DCA

A MO:DCA file can contain multiple pages, however, only a single page can be rendered to a DIB at one time. The ImageNumber field is used to select the desired page. It defaults to the first page in the file.

The dimensions of the output DIB default to PageWidth and PageHeight according to the values from the input file, but can be re-sized after REQ_INIT before REQ_EXEC by specifying OutHeight and OutWidth, or OutXRes, OutYRes and OutResUnits. Otherwise these values are set according to the input file. If the file contains an IOCA object and any of these Out parameters require that the IOCA object be rendered at a different size than the actual IOCA object width and height, the opcode will internally call OP_ZOOM2. This can occur even when the Out* values aren't changed from their default values depending on the specifications of the input file. The user should provide a P2PktRegistration packet with OP_ZOOM2 registration codes in PicParm.PIC2List to avoid the OP_ZOOM2 registration message. See the PIC2List Functions section for more information.

The bit depth of the output DIB can be specified by setting OutBpp. The default is 1bpp for files containing no PTOCA objects and 8bpp for files containing PTOCA objects. Allowable values are 1 and 8 bpp.

The output DIB can be cropped to a specified sub-rectangle by setting F_InputCrop in PicParm.Flags and setting PicParm.IOCropXoff, PicParm.IOCropYoff, PicParm.IOCropWidth, and PicParm.IOCropHeight to describe the sub-rectangle. PicParm.IOCropXoff and PicParm.IOCropYoff are offsets within the image dimensions specified with the OutHeight/OutWidth or OutXRes/OutYRes fields.

Set MODCA.PicFlags |= PF_NoDibPad to avoid any padding of output lines otherwise output lines are padded to a multiple of 4 bytes.

To set a particular width for the output lines set PF_WidthPadKnown in PicFlags, and set WidthPad to the desired width in bytes.

If the Put queue is smaller than the full output image size, then rendering will take longer if the page includes any PTOCA objects, and also if F_UseDeferFn is specified for the non-coroutine mode API plus the page includes an IOCA object that requires OP_ZOOM2 to be rendered to the specified size. Under those conditions, the image rendering is banded into the Put queue such that there are N bands (N = <Output Image size> / <Put size>), then the image is rendered N * (N + 1 ) / 2 times - i.e., proportional to the number of bands squared.

If the Put queue size changes between calls to REQ_INIT and REQ_EXEC the opcode could internally render the same line multiple times for PTOCA objects causing performance to suffer. Especially if the size of the Put queue during REQ_EXEC is smaller than during REQ_INIT or if the Put queue size is larger during REQ_EXEC but not a multiple of the Put queue size during REQ_INIT.

Output DIB from CALS1 or IOCA

An output DIB from a CALS1 or IOCA file will be 1bpp and cannot be resized from the original image dimensions nor image resolution.

The output DIB can be cropped to a specified sub-rectangle by setting F_InputCrop in PicParm.Flags and setting PicParm.IOCropXoff, PicParm.IOCropYoff, PicParm.IOCropWidth, and PicParm.IOCropHeight to describe the sub-rectangle. PicParm.IOCropXoff and PicParm.IOCropYoff are offsets within the image dimensions.

Set MODCA.PicFlags |= PF_NoDibPad to avoid any padding of output lines otherwise output lines are padded to a multiple of 4 bytes.

To set a particular width for the output lines set PF_WidthPadKnown in PicFlags, and set WidthPad to the desired width in bytes.

Output DIB from C4

An output DIB from a C4 file will be 1bpp and cannot be resized from the original image dimensions nor image resolution.

If the file contains an embedded preview image, the opcode will return from REQ_INIT with the PF2_HasThumbnail flag set. To render the embedded preview, set MODCA.PicFlags |= PF_ExpandThumbnail.