This page describes flags that Datalogics added to the core PDF Library. It does not include descriptions of flags provided by Adobe Systems.

allowLossyCompression

The allowLossyCompression flag resides within the PDDocColorConvertParamsEx extended parameters block of the PDDocColorConvertPageEx call, and can help to reduce output file size by enabling lossy compression in place of the default lossless compression.

Coding Sample

PDColorConvertParamsEx myColorParams =
(PDColorConvertParamsEx)malloc(sizeof(PDColorConvertParamsRecEx));
memset(myColorParams,0,sizeof(PDColorConvertParamsRecEx));
myColorParams->mSize = sizeof(PDColorConvertParamsRecEx);
myColorParams->allowLossyCompression = true;
ASBool bValue, result; PDDocColorConvertEmbedOutputIntent(pdDoc, prof);
for (int i=0; i<numPages; i++)
{
result = PDDocColorConvertPageEx(pdDoc, myColorParams, i, NULL, NULL, 0, NULL, &bValue);
}

Its default setting is False, so that past application behavior will be unchanged when applying a new release containing this enhancement, unless you set the flag.

FontRescan_All

This flag is used by the PDFLRescanFontDirectories call to indicate that all font resource areas should be searched once again. This is one of the enumerated flags of FontRescanFlags (defined in DLExtrasExpT.h) to specify the extent of the font resource rescanning to perform.

FontRescan_Files

As with the FontRescan_All flag (above), this flag is used by the PDFLRescanFontDirectories call. The FontRescan_Files flag directs that only those resource locations specified in the dirList array (including those added via the PDFLAddFontDirectories call) should be searched again.

FontRescan_System

As with the FontRescan_All and FontRescan_Files flags (above), this flag is used by the PDFLRescanFontDirectories call. The FontRescan_System flag directs that only the system resource locations should be searched again. Those in the dirList are not rescanned by this flag.

HalftoneGrayImages

The HalftoneGrayImages flag allows you to turn halftone processing of images on or off. If set to True, when TIFF images are rendered from PDF document pages, these images will be rendered as gray halftones automatically. If this flag is set to False, you can use the MonochromeThreshold property to manually adjust the quality of your output. This is not recommended for resolutions of 300 DPI or less.

The MonochromeThreshold property controls the level of shading for graphics when rendering PDF document pages to TIFF files. You can adjust the effects of converting to 1-bit monochrome output by setting this property in the ImageSaveParams class of the Java & .NET Interface, choosing a value from 0 to 255 (defaults to 128). The value makes the system more sensitive to subtle shading within an image. The higher the Threshold number, the more shaded pixels in an image will be presented as solid black, to make faint objects appear more clearly. This is particularly useful if it is necessary to sharply render bar code images so that scanning devices can read them easily.

See the description of the DocToImages sample program in Converting PDF Pages to Images, one of the samples provided with the Java and .NET Interface.

kDocEmbedSubset

This flag has been added to the PDDocEmbedFonts call to specify that fonts should be subset when embedded.

kDoNotMergeFonts

The kDoNotMergeFonts flag has been introduced for the PDEContentAddPage API. If specified, this flag allows the font merging process to be bypassed in cases where the default font consolidation is not needed, and where it may consume excessive processing time if allowed to proceed.

A document being created via an Import Pages operation, compiling one output document from multiple merged input pages, can take massive amounts of time (10-15 minutes) to complete what should be a relatively simple page-merging operation if the pages each contain a large number of fonts. In normal processing, every font will trigger a merge and consolidation operation when merging the input page with the resulting output, plus a repeat of the same process if Linearized output has been specified. This flag will suppress that operation for time-saving purposes in cases where it is not needed.

As part of this, a PDInsertDoNotMergeFonts flag has been added to the flag set accepted by PDDocInsertPages, passed via an internal call from PDEContentAddPage to PDDocInsertPages.

kDocEmbedSubsetOfEmbeddedFont

As with kDocEmbedSubset (above), this flag was added to the PDDocEmbedFonts call. This flag specifies that fonts already embedded should be re-embedded in subset form (see PDDocEmbedFonts).

kPDFLInitAvoidGDIFontScanner

The kPDFLInitAvoidGDIFontScanner flag resides within the PDFLDataRec of the PDFLInit call, and can, under some circumstances, speed up the initialization of CoolType on Windows.

If you are initializing several processes in parallel, and you have thousands of fonts in your resource locations, you may see delays due to locking and contention in the Windows Graphics Device Interface (GDI). This is caused by the GetFontData Windows API call normally used internally by the Library to find and parse TrueType font files.

Internal changes to CoolType were made so that it will attempt to find and parse the TrueType font files directly, as opposed to relying on a GetFontData call, and the kPDFLInitAvoidGDIFontScanner flag was added on the flags member of the PDFLDataRec to allow user control. The default value is False, to continue the past initialization practice if no problems have been observed.

This flag is best used under the following circumstances:

• Running on Windows
• Using many fonts ( thousands or more)
• Starting Adobe PDF Library on multiple, parallel servers
• When performance testing shows that startup performance of Adobe PDF Library is an issue
• When CPU usage for several servers seems to be capped at the use of one processor core
• When it is acceptable to have slight changes in which font is found, in the case of duplicate fonts with the same name

Testing for this flag is important, because some versions of Windows may not have the GDI resource contention problem; it should be used on an as-needed basis only.

Setting the flag may have an effect on later font selection in the case of multiple, similar font names. Specifically, if duplicate fonts have the same name, and especially if they are fonts of different types, such as Type 1 [.PFB] vs. Open Type or TrueType, the font that is ultimately chosen may vary depending on the state of this flag.

NOTE: We recommend that you do not use duplicate fonts.

If you are having a problem with startup initialization time in multiple, simultaneous process startups, set the kPDFLInitAvoidGDIFontScanner flag on the flags member of the PDFLDataRec, and look for a performance  improvement.

Coding Sample

int MyPDFLInit()
{
PDFLDataRec pdflData;
memset(&pdflData, 0, sizeof(PDFLDataRec)); pdflData.listLen =
PDFLGetDirList(&pdflData.dirList); pdflData.flags |=
kPDFLInitAvoidGDIFontScanner;

return PDFLInit(&pdflData);
}

Its default setting is False, so that past application behavior will be unchanged when applying this release, unless you set the flag.

 kPDFLInitDisableMemorySuballocator

This flag was added to the PDFLInit call to prevent memory suballocations if desired. When kPDFLInitDisableMemorySuballocator is added to the flags, each individual allocation will be passed to the C runtime or to the user-supplied allocator functions at the time it is requested, rather than allowing the standard Adobe PDF Library practice of reducing the number of memory allocations passed to the runtime library by obtaining larger segments of memory in (approximately) 64K chunks. In some applications, this flag has been seen to produce good performance improvements.

Normally, memory suballocation is used to reduce the number of memory allocations passed to the runtime library. In doing so, the library can avoid inefficiencies in speed or locality of reference (which affects paging) in the runtime library. This suballocation is done upstream of any allocator functions that you may supply, and will generally be seen as allocations in approximately 64000-byte chunks, rather than smaller increments in more-frequent occurrences.

However, when kPDFLInitDisableMemorySuballocator is added to the PDFLInit flags, each individual allocation will be passed to the C runtime or to the user-supplied allocator functions right away. Some reasons for doing this might include:

• Use of external debugging or leak checking tools that expect each allocation to be passed to malloc(), or to a special allocation call
• Special allocation needs
• Desire for all memory used by the library to be freed to the runtime immediately after it is internally freed

Some runtime libraries have a malloc() implementation that is very efficient and/or tuned for the operating system or hardware, and performance improvements have been seen when this flag is used.

Coding Sample

int MyPDFLInit()
{
PDFLDataRec   pdflData; memset(&pdflData, 0, sizeof(PDFLDataRec));
pdflData.size = sizeof(PDFLDataRec); pdflData.allocator =
PDFLGetMemAllocProcs();
pdflData.listLen     = PDFLGetDirList(&pdflData.dirList); pdflData.flags
= kPDFLInitDisableMemorySuballocator;
return PDFLInit(&pdflData);
}

 kPDPageDoNotDownloadFonts

This flag is part of the PDPageDrawFlags enumeration. When set to true, the Adobe PDF Library converts embedded/subset fonts in the PDF file into polygons or lines when drawing, removing the text characters and replacing them by visual paths representing the text. This eliminates font dependencies when generating portable Windows Metafiles.

kPDPageImageAntiAlias / kPDPageImageResampleBicubic/ kPDPageImageResampleLinear

These image smoothing flags permit fine-grained control of the rendering process by your application.

The software has three flags, including a separate AntiAlias setting flag;

drawParams.smoothFlags |= kPDPageImageResampleLinear;
drawParams.smoothFlags |= kPDPageImageResampleBicubic;
drawParams.smoothFlags |= kPDPageImageAntiAlias;

As before, the kPDPageImageResampleLinear flag uses "nearest neighbor" interpolation for its output, and the kPDPageImageResampleBicubic flag uses bicubic interpolation. However, only the kPDPageImageAntiAlias flag will turn on anti-aliasing; none will be performed if that flag is not given.

Anti-aliasing may be applied as needed, based on your preference of output. The legacy options will supersede the discrete options.

kPDPageNoDither

This flag allows you to suppress dithering when converting a PDF document to a 1-bit (black and white) DeviceGray image via either PDPageDrawContentsToMemory or PDPageDrawContentsToWindowWithParams.

Dithering provides a simulation of grayscale, but may not provide the effect that you want, so the kPDPageNoDither flag was introduced to allow control of dithered output as desired:

 Dithered vs. Non-Dithered Conversion

To suppress dithering in PDPageDrawContentsToMemory or PDPageDrawContentsToWindowWithParams, use “OR” for the value "kPDPageNoDither" into the "flags" parameter.

NOTE: This will suppress dithering only if csAtom is "DeviceGray" and the bit setting is 1.

kPDPageUsePreciseColorConv

When rendering a page to a bitmap, the Adobe PDF Library uses a "fast" 8-bit color profile conversion which provides relatively quick conversion processing with reduced memory consumption. However, comparing its results to output from a PDPageColorConvert operation will show very slight differences, since PDPageColorConvert uses a precise 15-bit color rendering algorithm instead.

Therefore, an optional PDPageDraw flag named kPDPageUsePreciseColorConv has been added to the available set. When set to true, the Library will use a precise 15-bit color transformation when rendering a page to bitmap, rather than the standard 8-bit fast one. When false (the default setting), the previous performance and rendering results will be maintained. The result of setting this flag, in other words, is that the conversion will run a bit slower, and use a bit more memory, but the results will be more precise as compared to the original.

kPDPrintUseMediaBox

This flag is part of the PDFLPrintUserParamsRec structure, with the paperHeight and paperWidth elements. This flag enables you to specify that PDFLPrintUserParamsRec output size values (paperHeight and paperWidth) should be set by the PDF document’s MediaBox values, on a page-by-page basis:

rec.paperHeight = kPDPrintUseMediaBox;
rec.paperWidth = kPDPrintUseMediaBox;

NOTE:  Do not confuse this kPDPrintUseMediaBox usage with the setPageSize parameter. This flag appears to do similar work, but it is an element of the Post Script parameter s structure (psParams ), not  PDFLPrintUserParamsRec. The setPageSize parameter is overridden by the paperHeight and paperWidth parameters when printing to a file.

kPDPrintUseCropBox

This flag is part of the PDFLPrintUserParamsRec structure, with the paperHeight and paperWidth elements. This flag enables you to specify that PDFLPrintUserParamsRec output size values (paperHeight and paperWidth) should be set by the PDF document’s CropBox values, on a page-by-page basis:

rec.paperHeight = kPDPrintUseCropBox;
rec.paperWidth = kPDPrintUseCropBox;

NOTE:  Do not confuse this kPDPrintUseCropBox usage with the setPageSize parameter. This flag appears to do similar work, but it is an element of the Post Script parameter s structure (psParams ), not  PDFLPrintUserParamsRec. The setPageSize parameter is overridden by the paperHeight and paperWidth parameters when printing to a file.

noSkewedQuads

This flag is part of the PDWordFinderConfigRec structure for WordFinder use. When true, it disables the creation of a quad per character for skewed words, those with a horizontally-aligned, but non-rectangular, bounding region.  Each skewed word will, instead, be associated with a single rectangular, bounding region.

noValidationErrors

For PDFProcessorPDFAConvertParamsRec, if the the noValidationErrors flag is set to True, it allows the Library to ignore validation errors and continue to create a PDF/A document.

If a validation error occurs, if this flag is set to False (the default value), the Library will not ignore the validation error. It will rasterize the page if the noRasterizationOnFontErrors flag is set to True.  It will generate an error message if the noRasterizationOnFontErrors flag is also set to False, “Conversion error occurred. Rasterization is OFF.”

Note that if the noValidationErrors flag is set to True, and noRasterizationOn FontErrors is also set to True, no pages can be created that contain constructs that exceed the limits set for the PDF/X-1b format standard. These will be treated as preflight errors for the PDF/A preflight check. This would include a document with a dictionary with more than 4097 entries, an array with more than 8192 entries, or a PDF with internal number values exceeding 31767, positive or negative. This matches legacy behavior.

PDDoNotSaveFileAttributes

This flag is part of the saveFlags2 bitfield of the PDDocSaveParams structure passed to PDDocSaveWithParams. It suppresses the default practice of preserving the input file’s attributes when saving PDF files opened originally from existing ones. Use this flag in cases where you do not want to save the new file output with the file attributes of the original, such as when reading from one location and writing to another.

PDInsertDoNotRemovePageInheritance

When inserting pages from a set of source documents into a new output PDF file, use this flag to turn off the function to remove the page inheritance, as this step can sometimes increase the processing time for a document with a very large page tree. The problem might appear when extracting pages from a large document to insert in a new one.

PDInsertDoNotResolveInvalidStructureParentReferences

When inserting pages from a set of source documents into a new output PDF file, sometimes the process can take a long time when the process tries to resolve problems with the document structure tree. Use this flag with the PDDocInsertPages API to direct the Adobe PDF Library to disregard the document structure tree.  This can significantly improve processing speed and performance when completing page insertions. The problem is rare, so in most cases you can set this flag and return to the performance you saw for other documents.

This flag is also exposed in the .NET and Java interfaces as part of the PageInsertFlags enumeration.

preciseQuad

The preciseQuad is a boolean flag offered with the PD Word Finder config record (PDWordFinderConfig). When set to Off (default), Word Finder behaves as usual; the bounding boxes returned by PDWordFinder reflect the character’s standard bounding boxes. When this flag is turned on, the bounding boxes and quads PDWordFinder returns reflect the actual outline of each glyph, without any additional space. The flag limits the bounding box to the exact size of the tallest and widest part of each word or character, so that Word bounding boxes are less likely to overlap.

The PDWordFinder is a tool in Adobe PDF Library that can identify all of the words in a PDF document and create a list or table of those words. By setting preciseQuad to On, this search process for PDWordFinder will be more accurate.