PICTools Programmer's Reference
OP_D2MDCA
| Operations > OP_D2MDCA |
OP_D2MDCA: Converts a DIB file to a MO:DCAor CALS1 file
OP_D2MDCA supports the creation of MO:DCA and CALS1 files from 1 bit per pixel DIBs.
In order to create a MO:DCA file containing the encoded DIB, you must make this input image available in the Get queue, and after encoding; a valid MO:DCA file will be placed in the Put queue. Q_REVERSE is not supported for the Put queue for OP_D2MDCA. At least StripSize bytes must be made available in the Get queue upon REQ_EXEC. See the MODCA_UNION structure for additional information.
A DIB can be appended to an existing MO:DCA file by setting PF_MultiImage in MODCA.PicFlags. The new DIB will be added as a new Page at the end of the MO:DCA document. The existing MO:DCA file is supplied to OP_D2MDCA using the Put queue. The Put queue does not have to be large enough to hold the entire MO:DCA file, but in this case, support for seeking is required. In the first case considered in the following, the Put queue is large enough to hold the entire existing MO:DCA file. In the second case, the Put queue is too small to hold the entire existing MO:DCA file.
Large enough Put queue:
In this case, read the existing file into the Put queue beginning at Put.Start, setting Put.Front to Put.Start, Put.Rear to the first byte following the file data and setting Q_EOF in Put.QFlags. If the Put queue is not large enough for the entire existing file plus the entire new page, RES_PUT_NEED_SPACE events will be returned as usual and can be handled normally. In that case, the Put queue can either be reallocated to a larger size or the Put queue data can be written to an output MO:DCA file beginning at file offset 0, advancing Put.Front to the first byte of data not written.
Put queue too small:
In this case, things are more complicated because existing file data is supplied using the Put queue and output file data is returned using the same Put queue.
Initially, the location pointed to be Put.Front is presumed to correspond to offset 0 in the existing MO:DCA file. When RES_PUTQ_GET_NEED_DATA is returned, the Put queue will be empty. You should read up to Put.End - Put.Start bytes of data from the existing MO:DCA file into the Put queue at Put.Start starting at file offset SeekInfo & SEEK_OFFSET. Set Put.Front to Put.Start and set Put.Rear to point to the byte following the last byte read from the existing file. Set Q_EOF in Put.QFlags if the end of the existing file is reached. Finally, restore the file offset to SeekInfo & SEEK_OFFSET. This is so a RES_PUT_NEED_SPACE can unconditionally be written to the file at the current file offset.
SeekInfo is set during RES_PUTQ_GET_NEED_DATA as a convenience. Successive RES_PUTQ_GET_NEED_DATA responses will always be sequentially contiguous in the existing file unless a RES_SEEK response is returned.
A RES_SEEK response will only be returned when the Put queue is empty. In that case, set the current file offset to SeekInfo & SEEK_OFFSET.
A RES_PUT_NEED_SPACE response can be handled as normally. Alternatively, if Q_READING is set in Put.QFlags, then the queue data was not modified by OP_D2MDCA. In that case, if the queue data are available at another location, the queue data can optionally be discarded instead of written.
If there are P2PktModca packets in the PIC2List these packets will be used instead of the opcode default values. All P2PktModca packets will be placed in the MO:DCA file in the order that they appear on the PIC2List.
You can add a Fully Qualified Name to the Begin Document SF by setting DocumentName. DocumentName is a NULL-terminated ASCII string. The DocumentName string will be converted to EBCDIC and copied to the FQN of the Begin Document SF. If there is a P2PktModca packet containing a Begin Document SF in the PIC2List the DocumentName will override the FQN in the P2PktModca packet. See PIC2List Functions for more information about adding P2PktModca packets.
In order to create a CALS1 file containing the encoded DIB, you must make this input image available in the Get queue, and after encoding; a valid CALS1 file will be placed in the Put queue. Q_EOF is set on the Put queue once the CALS1 file is created. At least StripSize bytes must be made available in the Get queue upon REQ_EXEC. See the MODCA_UNION structure for additional information.
The CALS1 header field default values can be overridden by placing P2PktCals packets in the PIC2List. Comments can also be added to the CALS1 file by adding a P2PktComment packet or setting PIC_PARM.Comment and PIC_PARM.CommentLength. See PIC2List Functions for more information about adding P2PktCals packets.