Using EPS Files in POSTSCRIPTR PostScript Language Forms Software From Adboe Adobe Developer Support Technical Note #5144 4 October 1996 Adobe Systems Incorporated Corporate Headquarters Adobe Systems Eastern Region 345 Park Avenue 24 New England San Jose, CA 95110 Executive Park (408) 536-6000 Main Number Burlington, MA 01803 (408) 536-9000 Developer Support (617) 273-2120 Fax: (408) 536-6883 Fax: (617) 273-2336 European Engineering Support Group Adobe Systems Co., Ltd. Adobe Systems Benelux B.V. Yebisu Garden Place Tower P.O. Box 22750 4-20-3 Ebisu, Shibuya-ku 1100 DG Amsterdam Tokyo 150 The Netherlands Japan +31-20-6511 355 +81-3-5423-8169 Fax: +31-20-6511 313 Fax: +81-3-5423-8204 PN LPS5144 Copyright 1996 by Adobe Systems Incorporated. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written consent of the publisher. Any software referred to herein is furnished under license and may only be used or copied in accordance with the terms of such license. PostScript is a trademark of Adobe Systems Incorporated. All instances of the name PostScript in the text are references to the PostScript language as defined by Adobe Systems Incorporated unless other- wise stated. The name PostScript also is used as a product trademark for Adobe Systems’ implemen- tation of the PostScript language interpreter. Any references to a “PostScript printer,” a “PostScript file,” or a “PostScript driver” refer to printers, files, and driver programs (respectively) which are written in or support the PostScript language. The sentences in this book that use “PostScript language” as an adjective phrase are so constructed to rein- force that the name refers to the standard language definition as set forth by Adobe Systems Incorpo- rated. PostScript, the PostScript logo, Display PostScript, Adobe, the Adobe logo, Adobe Illustrator, Adobe PageMaker, Adobe PrePrint, Adobe TrapWise are trademarks of Adobe Systems Incorporated regis- tered in the U.S.A. and other countries. FrameMaker is a registered trademark of Frame Technology Corporation. Helvetica and Times are trademarks of Linotype AG and/or its subsidiaries. QuarkXPress is a registered trademark of Quark, Inc. Macromedia FreeHand is a trademark of Macromedia, Inc. This publication and the information herein is furnished AS IS, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorpo- rated assumes no responsibility or liability for any errors or inaccuracies, makes no warranty of any kind (express, implied or statutory) with respect to this publication, and expressly disclaims any and all warranties of merchantability, fitness for particular purposes and noninfringement of third party rights. Contents Using EPS Files in PostScript Language Forms 5 1 Introduction 5 2 Storing the EPS file in VM 5 Example 1 Code Walk-through 5 3 Emulating 1-page forms in a Level 1 environment 9 Example 2 Code Walk-through 10 4 Performance Advantage of PostScript Forms 17 5 Storing an EPS on a writeable drive, for use in a Form 18 Steps for Writing an EPS file to disk for use in a form 19 Fine Tuning Example 3 22 6 Setting the Form Cache 23 7 Debugging Your Test Files 24 Emulating the execform operator 24 Testing whether a form is cached 25 8 Summary 25 Index 27 iii iv 4 Oct 96 Using EPS Files in PostScript Language Forms 1 Introduction In PostScript Level 2, Adobe introduced the execform operator to support the caching of graphical objects or “forms” for repeated use. In order to ensure that each execution of a form produces the same output, it must be com- pletely self-contained and conform to several constraints. One of these con- straints is that all graphical content must be described within the form’s PaintProc. Since the PaintProc is a procedure, it may not contain references to in-line data. This restriction, as well as the implementation size limits for procedures and strings, could present obstacles to placing an encapsulated PostScript (EPS) file in a form. Using an EPS file in a form is possible, however, provided the user has ade- quate VM or a writeable storage drive. This paper will explain how to accom- plish this, and will provide some emulation code for Level 1 devices. 2 Storing the EPS file in VM Placing an EPS file into a form’s PaintProc is not simply a matter of taking the EPS file and bracketing it with curly braces. This would likely result in PostScript error messages, for a number of reasons. For example, EPS files often contain in-line data for fonts or images, which are inappropriate con- tents for any procedure. (See the Q&A section of the ADA News, volume 3, issue number 1, for an explanation of why in-line data will not work in a pro- cedure body.) Instead, an EPS file can be executed by a PaintProc with the use of the SubFileDecode filter. Example 1 below shows how this is done. 2.1 Example 1 Code Walk-through In example 1, we store the contents of an EPS file in an array of strings. Then, we define a form with a PaintProc that consecutively executes each string in the array. The primary tasks performed by the code are as follows: 1. The readdata procedure, called prior to the inclusion of the EPS file, con- sumes the EPS file and puts its contents into an array of strings, EPSArray. 5 We have chosen a string buffer size of 16000 bytes to avoid premature VMerrors as the result of fragmentation of VM. The initial entry in EPSArray is a 1-element array, containing a counter. The counter is stored in an array so that it can be maintained in global VM, and thereby be unaffected by calls to save or restore encountered when executing the EPS file. The following n entries are strings containing the EPS contents. n can be determined by dividing the size of the EPS file by 16000 (the string size) and rounding up. Lastly, an empty string must be present in the array, immediately following the EPS strings, to indicate the end of data. 2. After the EPS file, we place the comment: % EOD_Marker_4386 in the output file. The SubFileDecode filter in the readdata procedure uses this comment as an end-of-data marker. The last four numbers are generated randomly when the file is created. You may choose to use any numbers or characters for this comment; however, it is important that you vary the comment for each job to avoid problems that may occur when nesting exe- cutions of SubFileDecode. 3. We define the form resource in the document set-up section of the output file. The BBox entry of the form has the same value as that offered by the %%BoundingBox: comment of the EPS file. The PaintProc procedure uses the SubFileDecode filter to execute the EPS file. The data acquisition procedure used with SubFileDecode, AcquisitionProc, traverses EPSArray, providing the EPS strings to the filter on demand. The execution of the EPS file is contained within the context of the StartEPSF and EPSFCleanUp procedures, which serve to create and restore the proper PostScript environment for the EPS file. These pro- cedures are identical to what would be used to import an EPS file, regard- less of its use in a form; this process is described in section H.3.2 of the PostScript Language Reference Manual, Second Edition. 4. Within the individual page descriptions, we execute the form by calling the execform operator. Three pages, containing the EPS file, are printed in this example. Note Prior to executing the code below, your application should determine that there is adequate free VM to store the EPS file. If there is limited free VM, you may need to include the EPS file multiple times within the job, rather than using forms. Alternatively, if the user’s output device has writeable storage, you may choose to store the EPS file on disk, as described in section 5 of this document. 6 Using EPS Files in PostScript Language Forms 4 Oct 96 Example 1: Executing EPS in form’s PaintProc %!PS-Adobe-3.0 %%Title: (Using EPS file in Form in VM) %%BoundingBox: 0 0 612 792 % UPDATE FOR EACH EPS %%DocumentProcessColors: Black % PROMOTE DSC COMMENTS FROM EPS %%LanguageLevel: 2 %%Pages: 3 %%EndComments %%BeginProlog %%BeginResource: procset forms_ops 1.0 0 %%Title: (Forms Operators) %%Version: 1.0 userdict /forms_ops 10 dict dup begin put /StartEPSF { % prepare for EPSF inclusion userdict begin /PreEPS_state save def /dict_stack countdictstack def /ops_count count 1 sub def /showpage {} def } bind def /EPSFCleanUp { % clean up after EPSF inclusion count ops_count sub {pop} repeat countdictstack dict_stack sub {end} repeat PreEPS_state restore end % userdict } bind def /STRING_SIZE 16000 def % Best value to not fragment printer's VM /ARRAY_SIZE 40 def % UPDATE FOR EACH EPS == filesize/16000 + 2 % for initial counter and final empty string. /buffer STRING_SIZE string def /inputFile currentfile 0 (% EOD_Marker_4386) /SubFileDecode filter def /readdata { % array readdata -- 1 { % put counter on stack % stack: array counter 2 copy % stack: array counter array counter inputFile buffer readstring % read contents of currentfile into buffer % stack: array counter array counter string boolean 4 1 roll % put boolean indicating EOF lower on stack STRING_SIZE string copy % copy buffer string into new string % stack: array counter boolean array counter newstring put % put string into array not {exit} if % if EOF has been reached, exit loop. 1 add % increment counter } loop % increment counter and place empty string in next position 1 add 2 copy () put pop currentglobal true setglobal exch 0 1 array put % create an array for counter in global VM, % so as not to be affected by save/restore calls in EPS file.