PeachDrawing.PDF
PdfComposerOptions Class
What a PdfComposer writes into the file besides the pages: the document information, the PDF version and conformance level, color management, encryption, embedded files and how streams and images are compressed.
public sealed class PdfComposerOptions
Inheritance System.Object → PdfComposerOptions
Remarks
The options are read when they are applied - by the PdfComposer constructor, or by Configure(PdfComposerOptions) - so changing the object afterwards does not change a document in progress. A document’s format settings (version, conformance, color, encryption, embedded files) are fixed by the first application: applying options that ask for different ones to the same composer is rejected, rather than leaving a file whose header disagrees with how some of its pages were written. The document information may change from one application to the next.
| Properties | |
|---|---|
| Author | The name of the person who made the document, or null for none. |
| BrotliCompression | Whether page content, fonts, embedded files and raster image data are compressed with Brotli (the PDF 2.0 /BrotliDecode filter) instead of Flate: typically smaller output. Defaults to false, because the filter is not read by every PDF reader yet (PDFium, the engine behind Chrome’s and Edge’s viewers, and Acrobat show such a file as blank), so enable it only when you control the readers. Only applies to a Pdf20 file, and not to PDF/A-4 or PDF/X-6, which allow only the standard filters. Brotli comes from .NET’s own encoder, or from the encoder a host registers with PeachDrawing.Text.Compression.BrotliCompression.SetCompressor; with neither, the writer falls back to Flate silently. |
| ColorOptions | Color management: the output intent PDF/X requires, and the color conversions to apply. null (the default) writes every color in the space it was made in, and PDF/A files get the bundled sRGB output intent. |
| CompressContentStreams | Whether page content streams are compressed. Defaults to true; turning it off gives a larger file whose drawing operators can be read in a text editor. |
| Conformance | The PDF/A level the file claims. Defaults to None. Cannot be combined with XConformance or Encryption. |
| CreationDate | When the document was made, or null to leave the date out so the same input always gives the same file. An XMP metadata packet (see WriteXmpMetadata) requires one. |
| Creator | The name of the program that made the content the file was written from, or null for none. |
| CustomXmpProperties | Extra elements to add to the XMP packet’s rdf:Description, for properties of schemas the writer does not know. Each element must be in the namespace of its schema, and the schema must be declared the way PDF/A requires. |
| DownscaleImages | Whether an image drawn smaller than its natural size is resampled down to the size it is drawn at. Defaults to true. |
| DownscaleQuality | The JPEG quality (1 to 100) of a downscaled image that is re-encoded as JPEG. Defaults to 70. |
| EmbeddedFiles | Files to embed in the document. Requires PDF/A-3 (or no PDF/A level) and no PDF/X level; each file name must be unique. |
| Encryption | Password protection and permissions for the file, or null (the default) to leave it unprotected. Cannot be combined with a PDF/A or PDF/X level. |
| FacturX | Marks the document as a Factur-X / ZUGFeRD e-invoice in its XMP metadata, or null (the default) for none. The invoice XML itself is one of EmbeddedFiles; the document must be PDF/A-3. |
| FlattenTransparency | Whether content that needs PDF transparency is flattened to an opaque bitmap when the claimed level (PDF/A-1, PDF/X-1a, PDF/X-3) forbids transparency, instead of being rejected. Defaults to false. |
| ImageCompression | How lossless raster images are embedded. Defaults to Auto. |
| JxlPassthrough | <b>Experimental.</b> Whether an opaque, upright, non-animated gray or RGB JPEG XL image is embedded as its original bytes with the /JXLDecode filter instead of being decoded and recompressed. Defaults to false. There is no published PDF filter for JPEG XL yet: the name and layout follow the only open-source design so far (an experimental PDFium decoder), so no shipping PDF reader opens such a file today. A JPEG XL with alpha, animation or CMYK always takes the normal raster path, as does any image under Lossy. Same version restrictions as BrotliCompression. |
| Keywords | Keywords for the document, separated as the author likes, or null for none. |
| Language | The document’s natural language as a BCP 47 tag (en-US), written as the catalog’s /Lang, or null for none. The accessible PDF/A levels (PdfA1A, PdfA2A, PdfA3A) require one. |
| Linearize | Whether the file is written in the linearized layout (“fast web view”, ISO 32000-1 Annex F): the first page’s objects come first, then the other pages in order, with hint tables, so a viewer fetching the file over a network can show the first page before the rest has arrived. Defaults to false. A linearized file is a little larger. |
| MaximumDownscaleMultiplier | How many times larger than the size it is drawn at a downscaled image may stay, to keep detail for zooming in. Defaults to 1.0: exactly the drawn size. |
| PortableColorFilters | Whether per-channel color effects (brightness, contrast, invert and the like) are written as blend-mode layers every PDF reader composites itself, instead of as a PDF transfer function (an ExtGState /TR). Defaults to false. The transfer function is exact for any content but some readers ignore it (MuPDF, and so the viewers built on it, draw the element unfiltered); the blend-mode layers filter the element in every reader, but are exact only where the content is opaque, and need a reader that supports PDF transparency (so they are rejected under PDF/A-1 and PDF/X-1a/X-3, like the default is). |
| Producer | The name of the program that converted the content to PDF, or null for the writer’s own (PeachDrawing.PDF and its version). |
| Subject | What the document is about, or null for none. |
| Title | The document’s title (shown in a reader’s title bar), or null for none. |
| UAConformance | The PDF/UA level the file claims. Defaults to None. Can be combined with Conformance but not with XConformance. A claim needs a tag recorder (CreateTagRecorder(bool)), a Title and a Language, and writes an XMP metadata packet (which needs CreationDate). |
| Version | The PDF version to write, or null (the default) to let the writer choose: Pdf20, except for the PDF/A and PDF/X levels defined against PDF 1.x, which get Pdf17. A version that contradicts the conformance level is rejected. |
| WriteXmpMetadata | Whether a document-wide XMP metadata packet is written. Always written when a PDF/A or PDF/X level is claimed or CustomXmpProperties is not empty. Requires CreationDate. |
| XConformance | The PDF/X level the file claims. Defaults to None. Needs a ColorOptions output intent. |