(v13) Adding new supported file types for OPI
This page applies to Harlequin v13.1r0 and later; both Harlequin Core and Harlequin MultiRIP.
Adding a new file type includes these four stages:
Naming
Select a name to tie the various parts of the process together. Keys used so far include /eps, /tiff, and /pceps.
Identifying the file type
If the file type may be adequately identified from a magic number at the start of the file, define an entry in the /HqnOPIHeaderCodes dictionary. The key should be a string defining the first few bytes of the file which identify it, and the value should be the name selected in the first step.
The key should be a string and the value a name, not the other way round.
If the file type cannot be safely identified from just a magic number, then define an entry in/HqnOPIidentify. The key should be the name of the file type, and the value should be a procedure. The procedure may read from a file object named HqnFileChannel (but should not close the file), and should return true to indicate that the file is of the specified type (or false to indicate that it is not).
Post processing
If there is any information required from the file in order to set colorspace, transfer functions, positioning, scaling, or other feature correctly, you should define a procedure in the /HqnOPIpostDetect dictionary. The procedure may read from a file object named HqnFileChannel (but should not close the file) and should leave the operand and dictionary stacks as they were when it started. It may update the information from the OPI dictionary supplied that is held in a dictionary named /HqnOPIdata —most commonly it may be useful to correct the value of /ColorType or /ImageType.
If the image is grayscale and subtractive (that is, 0 = white, 1 = black), the value of/OPIsubtractiveImage in HqnOPIdict should be set to true within this procedure.
Determining this data in a procedure in /HqnOPIidentify is not sufficient because there may be some circumstances in which the /HqnOPIidentify procedures are not called (for example, because HqnFileType was explicitly set in the OPI data dictionary).
Imaging
Finally, the high-resolution image data must actually be executed. You must provide a procedure in the /HqnOPIimageAction dictionary to do this. The procedure is called with the image data file object on the stack, and the file pointer is set to byte 0 (zero).
Operand and dictionary stack manipulation has already been performed and there is no requirement to include a save/restore context within the procedure. showpage, copypage, and setpagedevice has already been shadowed to prevent new pages being triggered within the image data.
Colorspace, transfer functions, positioning, scaling, and so on have been set as well as possible before the procedure is called.
Your procedure should include code to scale the high-resolution data to fit to a unit square.
When processing a grayscale image, your procedure must avoid explicitly or implicitly setting the colorspace to /DeviceGray, as that would prevent grayscale images tinted to other colors from being properly imaged.
The procedure should return true on the stack to indicate success (or false if the file does not run to completion).