Transparency Flattening Components and Deployment

This article applies to Windows 64, Linux x86_64 and MacARM versions of Datalogics Adobe PDF Library (APDFL) 21. Feature availability, component filenames, file sizes, and deployment requirements may differ on other platforms or in other APDFL versions.

Description

Transparency flattening prepares PDF artwork containing transparent objects and effects for workflows that require content without live transparency. It combines those effects into a representation suitable for the intended output.

This feature is useful when preparing documents for older printing equipment or processing systems that require flattened artwork. It helps applications meet the output requirements of those systems.

Samples

The installed sample is located at:
CPlusPlus\Sample_Source\ContentModification\FlattenTransparency\FlattenTransparency.cpp

It uses PDFlattenerConvertEx2 to flatten the supplied FlattenTransparency.pdf document, with configurable rasterization and compression settings.

Public sample (github): FlattenTransparency

Files

Paths are relative to the SDK root. Sizes are uncompressed file lengths, rounded to two decimal places. Sizes and savings may vary by SDK build.

Windows

DL210PDFlattener.ppi provides transparency flattening. No additional exclusive runtime dependency was identified for omission with this plug-in.

Linux x86_64

Symbolic links belonging to this component:

• CPlusPlus/Binaries/DL210PDFlattener.ppi → CPlusPlus/Binaries/DL210PDFlattener.ppi.21.0.0
• CPlusPlus/Binaries/DL210PDFlattener.ppi.21.0.0 → `CPlusPlus/Binaries/DL210PDFlattener.ppi.21.0.0.0

Shared settings component (retain when another dependent feature is used):

Symbolic links belonging to this component:

• CPlusPlus/Binaries/libDL210pdfsettings.so → CPlusPlus/Binaries/libDL210pdfsettings.so.21.0.0
• CPlusPlus/Binaries/libDL210pdfsettings.so.21.0.0 → CPlusPlus/Binaries/libDL210pdfsettings.so.21.0.0.1

Mac ARM

Paths are relative to the main SDK root, except the WebToPDF bundle and headers, which originate in the separate WebToPDF SDK. Sizes use 1 MB = 1,048,576 bytes (1,024² bytes) and are rounded to two decimal places. A displayed size of 0.00 MB may represent a nonempty file smaller than 0.005 MB. Directory totals include all regular-file contents recursively, including resources and signatures; symlink targets are counted once. Filesystem allocation and directory metadata are excluded.

Omitting the Feature When Unused

Windows

If transparency flattening is unused, omit DL210PDFlattener.ppi to save 0.30 MB.

The plug-in can be omitted when no retained workflow requires transparency flattening. PDFs containing transparency can still be opened, rendered, saved, and reopened without it. Those operations produced matching rendered pixels, text counts, and transparency status in the omission tests.

Linux x86_64

When the application does not perform transparency flattening, omit:

• CPlusPlus/Binaries/DL210PDFlattener.ppi
• CPlusPlus/Binaries/DL210PDFlattener.ppi.21.0.0
• CPlusPlus/Binaries/DL210PDFlattener.ppi.21.0.0.0

This saves 0.67 MB for the plug-in itself. With the listed exclusive components absent, APDFL initialization, PDF opening, text extraction, rendering, saving, reopening, and termination succeeded on the tested inputs. Word counts, rendered-image hashes, and document measurements matched the corresponding baseline. PDFs containing live transparency and previously flattened PDFs remained usable. Ordinary rendering of transparent page content did not require this plug-in.

The settings library is shared by XPS2PDF, PDFProcessor, and Transparency Flattening. Retain it if any of these three features remains in use. Only when all three are omitted can the following additional files be omitted, saving 0.26 MB once across the deployment:

• CPlusPlus/Binaries/libDL210pdfsettings.so
• CPlusPlus/Binaries/libDL210pdfsettings.so.21.0.0
• CPlusPlus/Binaries/libDL210pdfsettings.so.21.0.0.1

Retain the other APDFL libraries, including the ARE and PDFPort libraries, and the required fonts, CMaps, Unicode resources, and color profiles. Their removal is outside this omission list.

The positive flattening test processed one page and removed its live transparency. The resulting PDF remained usable without the plug-in.

MacARM

Native ARM64 tests established successful feature use before omission. With the components listed below absent, APDFL initialization, PDF opening, text extraction, rendering, saving, reopening, and termination succeeded for the tested documents. Extracted text and rendered pixels matched the corresponding baseline, including PDFs previously produced by the optional features.

Exact tested runtime omission list:

• CPlusPlus/Binaries/DL210PDFlattener.ppi` (entire directory)

Runtime payload savings: 0.55 MB. Development headers and samples are not included in this figure.

Retain `DL210PDFPort.framework` while PDFProcessor remains deployed. Retain `DL210pdfsettings.framework` while PDFProcessor or WebToPDF remains deployed. Keep shared rendering frameworks, including `DL210ARE.framework`, and APDFL fonts, CMaps, Unicode data, and color profiles. The tested PDF/A-1b and PDF/X-1a conversions still removed transparency when this plug-in was absent and the shared support frameworks remained. This result is limited to the tested conversion settings and inputs. Ordinary PDF rendering, conversion, and explicit transparency flattening remain separate application operations.

Application considerations

Windows

Remove unconditional PDFlattener initialization and conversion calls when the feature is omitted. For optional installation, check gPDFlattenerHFT after InitPDFlattenerHFT before invoking PDFlattenerInitialize or conversion APIs, and guard termination. The installed sample assumes the plug-in is available.

Transparency flattening is distinct from annotation flattening. The installed Annotations\FlattenAnnotations sample used core PDF APIs and removed 76 annotations in testing with DL210PDFlattener.ppi absent.

Review printing, PostScript output, and PDF/A or PDF/X conversion settings for indirect flattening requirements. This investigation does not establish that every such output configuration is independent of the plug-in. Retain APDFL core dependencies and required font, CMap, Unicode, and color-profile resources. Validate the final product's retained workflows in an isolated deployment.

Linux x86_64

Check that the PDFlattener HFT is available before calling `PDFlattenerInitialize()` or flattening APIs. Check initialization and handle APDFL exceptions. In a dependency test, the plug-in files remained present but removal of the shared settings library made the flattener HFT unavailable.

Flattening should be requested only when the output workflow requires it. The native baseline converted a page containing live transparency to a page without live transparency. This component addresses page artwork; it should not be confused with flattening form fields or annotations. Call `PDFlattenerTerminate()` after successful initialization and release page, document, path, and profile resources.

MacARM

Assign `gPDFlattenerHFT = InitPDFlattenerHFT` and check for a null table before `PDFlattenerInitialize()`. Check initialization and `PDFlattenerConvertEx2` results, and inspect the count of flattened pages. A zero page count does not demonstrate successful flattening of a document that actually contains transparency. Initialize the size fields of parameter records, provide a valid color profile, and release the profile text and document resources. Call `PDFlattenerTerminate()` only after successful initialization; never call it through a missing table in an error handler.

Removing files alone is insufficient if application startup or a document workflow unconditionally calls the feature. Feature availability, feature initialization, and successful completion of a requested operation are separate checks.

How to Get Additional Help

Contact Datalogics Tech Support 

Fetch the answers quickly using our AI assistant Scout, available for any language. Scout also opens access to our MCP server, connecting APDFL with your favorite AI tools for faster and easier coding.