MuPDF Explored Robin Watts July 30, 2021 Preface This is the beginnings of a book on MuPDF. It is far from complete, but offers useful information as far as it goes. We offer it with the latest release of MuPDF (currently 1.13) in the hopes it will be useful. Any feedback, corrections or suggestions are welcome. Please visit bugs. ghostscript.com and open a bug with \MuPDF" as the product, and \Docu- mentation" as the component. We will endeavour to make new versions available from the Documentation section of mupdf.com as they appear. i Acknowledgements Many thanks are due to Tor Andersson for creating MuPDF, to everyone who has contributed to it over the years, and to all my colleagues at Artifex Software for providing an environment in which it could grow, and nursing it through to maturity. Particular thanks are due to Sebastian Rasmussen for patiently proof-reading the book through its many revisions, and suggesting numerous improvements. Finally, many thanks are due to Helen Rogers, for putting up with me. ii Contents Prefacei Acknowledgements ii 1 Introduction1 1.1 What is MuPDF?...........................1 1.2 License.................................1 1.3 Dependencies.............................3 2 About this book5 I The MuPDF C API6 3 Quick Start7 3.1 How to open a document and render some pages.........7 4 Naming Conventions8 4.1 Prefixes................................8 4.2 Naming................................8 4.3 Types................................. 10 5 The Context 11 5.1 Overview............................... 11 5.2 Creation................................ 12 5.3 Custom Allocators.......................... 13 5.4 Multi-threading............................ 13 5.5 Cloning................................ 15 5.6 Destruction.............................. 16 5.7 Tuning................................. 17 5.8 Summary............................... 19 6 Error handling 20 6.1 Overview............................... 20 iii CONTENTS iv 6.1.1 Why is fz var necessary?.................. 22 6.1.2 Example: How to protect local variables with fz var ... 23 6.2 Throwing exceptions......................... 24 6.3 Handling exceptions......................... 25 6.4 Summary............................... 26 7 Memory Management and The Store 27 7.1 Overview............................... 27 7.2 Creating the Store.......................... 28 7.3 Reacting to Out of Memory events................. 28 7.3.1 Implementation........................ 28 8 The Document interface 29 8.1 Overview............................... 29 8.2 Opening/Closing a document.................... 29 8.3 Handling password protected documents.............. 31 8.4 Handling reflowable documents................... 31 8.5 Getting Pages from a document................... 33 8.6 Anatomy of a Page.......................... 34 8.7 Color Considerations......................... 34 8.8 Rendering Pages........................... 35 8.9 Presentations............................. 37 8.9.1 Querying........................... 37 8.9.2 Helper functions....................... 38 9 The Device interface 39 9.1 Overview............................... 39 9.2 Device Methods............................ 40 9.3 Cookie................................. 40 9.3.1 Detecting errors....................... 41 9.3.2 Using the cookie with threads................ 41 9.3.3 Using the cookie to control partial rendering....... 42 9.4 Device Hints............................. 42 9.5 Inbuilt Devices............................ 43 9.5.1 BBox Device......................... 43 9.5.2 Draw Device......................... 44 9.5.3 Display List Device...................... 46 9.5.4 PDF Output Device..................... 46 9.5.5 Structured Text Device................... 47 9.5.6 SVG Output Device..................... 48 9.5.7 Test Device.......................... 48 9.5.8 Trace Device......................... 50 10 Building Blocks 52 10.1 Overview............................... 52 10.2 Colorspaces.............................. 52 CONTENTS v 10.2.1 Basic Colorspaces...................... 52 10.2.2 Indexed Colorspaces..................... 53 10.2.3 Separation and DeviceN Colorspaces............ 53 10.2.4 Further information..................... 53 10.3 Pixmaps................................ 54 10.3.1 Overview........................... 54 10.3.2 Premultiplied alpha..................... 55 10.3.3 Saving............................. 55 10.4 Bitmaps................................ 55 10.5 Halftones............................... 56 10.6 Images................................. 57 10.7 Buffers................................. 57 10.8 Transforms.............................. 57 10.9 Paths................................. 63 10.10Text.................................. 64 10.11Shadings................................ 66 11 Display Lists 67 11.1 Overview............................... 67 11.2 Creation................................ 67 11.3 Playback................................ 68 11.4 Reference counting.......................... 69 11.5 Miscellaneous operations....................... 70 12 The Stream interface 72 12.1 Overview............................... 72 12.2 Creation................................ 72 12.3 Usage................................. 74 12.3.1 Reading bytes......................... 74 12.3.2 Reading objects........................ 76 12.3.3 Reading bits......................... 77 12.3.4 Reading whole streams.................... 78 12.3.5 Seeking............................ 79 12.3.6 Meta data........................... 80 12.3.7 Destruction.......................... 81 13 The Output interface 82 13.1 Overview............................... 82 13.2 Creation................................ 82 13.3 Usage................................. 84 13.3.1 Writing bytes......................... 84 13.3.2 Writing objects........................ 84 13.3.3 Writing strings........................ 85 13.3.4 Seeking............................ 86 14 Rendered Output Formats 87 CONTENTS vi 14.1 Overview............................... 87 14.2 Band Writers............................. 88 14.3 PNM.................................. 89 14.4 PAM.................................. 90 14.5 PBM.................................. 90 14.6 PKM.................................. 90 14.7 PNG.................................. 91 14.8 PSD.................................. 92 14.9 PWG/CUPS............................. 92 14.9.1 Contone............................ 94 14.9.2 Mono............................. 95 14.10TGA.................................. 96 14.11PCL.................................. 97 14.11.1 Color............................. 98 14.11.2 Mono............................. 99 14.12Postscript............................... 99 15 The Document Writer interface 101 15.1 Usage................................. 101 15.2 Implementation............................ 103 16 Progressive Mode 106 16.1 Overview............................... 106 16.2 Implementation............................ 107 16.2.1 Progressive Streams..................... 107 16.2.2 Rough renderings....................... 108 16.2.3 Directed downloads..................... 108 16.2.4 Example implementation.................. 110 17 Fonts 112 17.1 Overview............................... 112 17.2 Inbuilt Fonts............................. 113 17.3 Implementation............................ 114 18 Build configuration 115 18.1 Overview............................... 115 18.2 Configuration file........................... 115 18.3 Plotter selection........................... 116 18.4 Document handlers.......................... 117 18.5 JPEG 2000 support......................... 117 18.6 Javascript............................... 118 18.7 Fonts.................................. 118 19 Annotations, Links and Interaction 120 19.1 Overview............................... 120 19.2 Fitz-level Links............................ 121 CONTENTS vii 19.3 Fitz-level Annotations........................ 122 19.4 PDF-level Annotations and Widgets................ 122 19.4.1 How to operate at the PDF level.............. 122 19.4.2 PDF Annotations...................... 123 19.4.3 Annotation Values vs Appearances............. 124 19.4.4 Updating annotations.................... 125 19.5 PDF Annotation operations..................... 125 19.5.1 PDF Widgets......................... 126 19.5.2 Events............................. 127 19.5.3 Event Callback........................ 129 II MuPDF Internals 131 20 The Image interface 132 20.1 Overview............................... 132 20.2 Standard Image Types........................ 134 20.2.1 Compressed.......................... 134 20.2.2 Decoded............................ 136 20.2.3 Display List.......................... 137 20.3 Creating Images........................... 137 20.4 Implementing an Image Type.................... 139 20.5 Image Caching............................ 142 21 The Document Handler interface 143 21.1 Overview............................... 143 21.2 Implementing a Document Handler................. 144 21.2.1 Recognize and Open..................... 144 21.2.2 Document Level Functions................. 146 21.2.3 Page Level Functions..................... 149 21.3 Standard Document Handlers.................... 152 21.3.1 PDF.............................. 152 21.3.2 XPS.............................. 153 21.3.3 EPUB............................. 153 21.3.4 HTML............................. 153 21.3.5 SVG.............................. 153 21.3.6 Image............................. 153 21.3.7 CBZ.............................. 153 22 Store