Export to .pdf File Parameters and Flags

The PDF export process can be managed with a set of parameters and flags that determine how the export should be executed. These parameters and flags are contained in a PDFExportParams class instance.

PDF export parameters are listed in the table below.

Export parameter name	Description	Get-method	Set-method
Database for export	A pointer to a database to be exported to a .pdf file.	`database()`	`setDatabase()`
Output stream for writing to .pdf file	A reference to an OdStreamBuff pointer, representing the output stream object to be used for writing data to a .pdf file.	`output()`	`setOutput()`
Version	Version of the output .pdf file. See the list of supported versions in the `PDFExportVersions` enumeration.	`version()`	`setVersion()`
Layouts to export	Array of the layouts that are exported to the output .pdf file. If the array has no elements, only the active layout is exported. See Export Layouts and Set Page Parameters for more information.	`layouts()`	`setLayouts()`
Page parameters	Array of the page parameters (paper size, margins, etc.) of the exported layouts. Count of elements must be equal to the count of the elements of the layout array. See Export Layouts and Set Page Parameters for more information.	`pageParams()`	`setPageParams()`
Background color	Background color of the output .pdf file. White is the default value.	`background()`	`setBackground()`
Palette	Palette for the output .pdf file. If not specified (NULL), one of two default palettes are used depending on the background color.	`palette()`	`setPalette()`
Color policy	Color policy used for creating export output. See Export to a Monochrome or a Grayscale .pdf File for details.	`colorPolicy()`	`setColorPolicy()`
Vectorizing resolution	Resolution used for vectorizing the output .pdf file (in dots per inch, DPI). Standard values are: 72, 150, 200, 300, 400, 600, 720, 1200, 2400 and 4800 DPI. Default value is 600 DPI.	`getGeomDPI()`	`setGeomDPI()`
Hatch export resolution	Resolution for images created during hatch export (in dots per inch, DPI). See Export Hatches for details.	`hatchDPI()`	`setHatchDPI()`
Resolution for color and grayscale images	Resolution for exported color and grayscale images (in dots per inch, DPI).	`colorImagesDPI()`	`setColorImagesDPI()`
Resolution for monochrome images	Resolution for exported monochrome images (in dots per inch, DPI).	`bwImagesDPI()`	`setBWImagesDPI()`
Image cropping	Determines how clipped images are exported. An image can be clipped by a clipping boundary (for example, by the boundary of a page in a .pdf file or by a viewport boundary). If equal to false, clipped images are exported as full images; in the other case only the visible part of images are exported.	`imageCropping()`	`setImageCropping()`
Image DCT compression	Determines whether the Discrete Cosine Transformation (DCT) compression algorithm is used for exporting images. If the value is equal to true, images are represented in the JPEG format. Using DCT compression significantly reduces of the output .pdf file size.	`dctCompression()`	`setDCTCompression()`
Image DCT compression quality	Determines the quality of image DCT compression (JPEG format) and is applied only if the Image DCT parameter is equal to true. The parameter value can be between 10 and 100 and determines the quality of the compressed image relative to the original image. The default value is 50.	`dctQuality()`	`setDCTQuality()`
Solid hatch export type	Algorithm used for exporting solid hatches. See Export Hatches for details.	`solidHatchesExportType()`	`setSolidHatchesExportType()`
Gradient hatch export type	Algorithm used for exporting gradient hatches. See Export Hatches for details.	`gradientHatchesExportType()`	`setGradientHatchesExportType()`
Other hatch export type	Algorithm used for exporting non-solid and non-gradient hatches. See Export Hatches for details.	`otherHatchesExportType()`	`setOtherHatchesExportType()`
Output document's title	Title of the output .pdf file.	`title()`	`setTitle()`
Output document's author	Name of the person who created the output .pdf file.	`author()`	`setAuthor()`
Output document's subject	Subject of the output .pdf file.	`subject()`	`setSubject()`
Output document's keywords	Keywords associated with the output .pdf file.	`keywords()`	`setKeywords()`
Output document's creator	Name of the application (for example, Adobe® FrameMaker®) that was used to create the original drawing document.	`creator()`	`setCreator()`
Output document's producer	Name of the application (for example, Adobe Acrobat® Distiller) that was used to convert the original drawing to the output .pdf file.	`producer()`	`setProducer()`
PRC support	Determines how PRC format is supported during the export process. See PRC Support for more information.	`PRCMode()`	`setPRCMode()`
PRC compression	Determines whether compression for PRC data is supported during the export process. You can separately set the compression level for both B-Rep and tessellation data. See PRC Support for more information.	`PRCCompression()`	`setPRCCompression()`
PRC context	Contains the PRC data to export, which can be filtered to include specific entities to export into a PRC stream. See PRC Support for more information.	`getPRCContext()`	`setPRCContext()`
PRC background color	Defines the background color of PRC data created as a result of the export operation. To determine whether the background color differs from the default color white, use the `hasPrcBackground()` method. To return the default background color for PRC data, call the `clearPrcBackground()` method. See PRC Support for more information.	`getPrcBackground()`	`setPrcBackground()`
PRC rendering mode	Defines the rendering mode for the exported PRC content.	`getPrcRenderingMode()`	`setPrcRenderingMode()`
Shaded viewport export	Determines the export mode for viewports in shaded rendering mode. See Export of Shaded Viewports for details.	`shadedVpExportMode()`	`setShadedVpExportMode()`
Transparency of shaded views background	This parameter determines whether backgrounds of shaded views exported with a GS device are transparent. The `true` value indicates transparency; the `false` value indicates opaqueness.	`transparentShadedVpBg()`	`setTransparentShadedVpBg()`
Disable GS device	Disables the GS device that is used for exporting shaded views. If the parameter value is equal to true, the GS device is disabled; otherwise (by default) the GS device is enabled. ODA Software supports exporting to PDF as geometry for wireframe and for wireframe with hidden lines (if the hidden lines removal algorithm is switched on). For other rendering modes (for example, shaded), the content is exported as an image, which is inserted into an output .pdf file afterward. Although for particular circumstances, the drawing can have the same look for different rendering modes (for example, a circle for wireframe and shaded modes). In such cases, exporting a drawing as an image has a disadvantage when scaling the output PDF content. Therefore it is better to export such entities as geometry despite the rendering mode. To do it, switch off the GS device (set the option equal to true) and the drawing content will be exported as geometry without dependency on the rendering mode. However, using this option can cause an incorrect rendering result in the output PDF document, so be careful. In general, it is NOT recommended to disable the GS device used for the export process.	`forceDisableGsDevice()`	`setForceDisableGsDevice()`
GSCache Usage	Determines whether GsCache is used within a PDF export operation. For additional information see the Use GsCache During Export section.	`useGsCache()`	`setUseGsCache()`
Export with searchable text	Determines whether text from an original drawing can be searched in the output .pdf file. This parameter is used only if text with a SHX or TTF font is exported as geometry. This parameter can accept one of four values: kNoSearch (0) - Default value: no searchable text in the output. kSHX (1) - Text that displays with SHX fonts is searchable if the SHX text as geometry flag is switched on. Text that displays with a TTF font is not searchable. kTTF (2) - Text that displays with TTF fonts is searchable if the TTF text as geometry flag is switched on. Text that displays with a SHX font is not searchable. kSHX\|kTTF (3) - Text that displays with either a SHX or TTF font is searchable if the text is exported as geometry. For each searchable text entity represented as geometry, an annotation that contains the text content of the entity is added.	`searchableTextType()`	`setSearchableTextType()`
Using view extents	Determines whether the export process should use view extents (if equal to true) or not (if equal to false). If this flag is set to true, the view extents are used instead of plot extents (which is used by default) when calculating the exported drawing extents. A drawing can contain entities that are considered in the calculation of the extents, but these entities are not rendered (for example, an empty multiline text entity, entities on hidden layers, etc.). View extents mode (flag is true) assumes that all invisible entities are taken into account when extents are calculated. Plot extents mode (flag is false) assumes that such entities are excluded from the extents calculations.	`useViewExtents()`	`setUseViewExtents()`
Watermarks	Contains an array of watermarks associated with the output PDF document. See Work with Watermarks for more information.	`watermarks()`	`addWatermark()`

The PDF export flags are stored in the setExportFlags() enumerator, which is a member of the PDFExportParams class. PDF export options are determined by the parameters' values and combination of parameter flags.

Default combination of export flags is kTTFTextAsGeometry|kSHXTextAsGeometry|kFlateCompression|kASCIIHexEncoding|kZoomToExtentsMode, i.e.:

TTF text as geometry flag is switched on.
SHX text as geometry flag is switched on.
Data compression flag is switched on.
Hexadecimal encoding flag is switched on.
Zoom to extents mode is switched on.
Other flags are switched off.

Some export flags are not recommended for use because they are deprecated or can be removed or changed in the next versions of the ODA Platform. See Deprecated Export Flags for details.

PDF export flags are described in the following table.

Export parameter	Parameter name	Value	Description
Use embedded TTF	kEmbededTTF	1	Enable embedding of True Type font files in the .pdf file. See Export Fonts for more information.
TTF text as geometry	kTTFTextAsGeometry	2	Enable True Type font text to geometry conversion. See Export Fonts for more information.
SHX text as geometry	kSHXTextAsGeometry	4	Enable SHX font text to geometry conversion. See Export Fonts for more information.
Use geometry optimization	kSimpleGeomOptimization	8	Determines whether simple geometry optimization is enabled during the export process (separated segments combined to one polyline, Bezier curve control points). See Geometry Optimization for more information.
Enable layers support	kEnableLayers	16	Determines whether layer support is enabled, in which case layers are added to the output .pdf file. See Export Layers for more information.
Include invisible layers	kIncludeOffLayers	32	Determines whether invisible layers of the exported drawing are added to the output .pdf file. See Export Layers for more information.
Embedded TTF optimization	kEmbededOptimizedTTF	64	Enables reducing the True Type font file size that is embedded in the output .pdf file. See Export Fonts for more information.
Use hidden lines removal algorithm	kUseHLR	128	Determines whether software vector hidden-line removal (HLR) is used to delete hidden lines during the export process for corresponding viewports. If this flag is equal to true, the drawing contents in wireframe mode is exported as geometry. If it is equal to false, the content is exported as an image.
Data compression	kFlateCompression	256	Determines whether a data compression algorithm is applied when writing drawing data in the internal PDF stream. See Use Data Compression and Hexadecimal Format for more information.
Hexadecimal encoding	kASCIIHexEncoding	512	Determines whether data is written in the internal PDF stream as hexadecimal format. See Use Data Compression and Hexadecimal Format for more information.
Exporting hyper links support	kExportHyperlinks	1024	Enables exporting hyperlinks to the output .pdf file.
Zoom to extents mode	kZoomToExtentsMode	2048	Determines whether the exported drawing is in the Zoom to Extents mode. If enabled, the layout geometry will be zoomed to the paper size, otherwise layout settings are applied.
Create a linearized .pdf file	kLinearized	4096	Determines whether the export process creates a linearized .pdf file from the exported drawing. See Export to a Linearized .pdf File for more information.
Merge crossing lines colors	kMergeLines	8192	Determines whether the colors of crossing lines are merged.
Measuring scale	kMeasuring	16384	Determines whether the measuring scale is implemented for the entities in the output .pdf file.

Special values of flags can also be used:

kZeroFlag (0) means that all flags are disabled.
kDefault stores the default value of the flag combination.

To get the current combination of export flags, use the exportFlags() method of the PDFExportParams class.

To set a new combination of export flags as the current one, use the setExportFlags() method of the PDFExportParams class.

Export Layouts and Set Page Parameters

Each drawing has one or several layouts that represent model space or paper space. To export specified layouts to the output .pdf file, add the layout name in the array: Layouts to export. If the array is empty, only the active layout is exported. Page count of the output .pdf file depends on the element count in this array.

The ability to set page parameters for the output .pdf file depends on whether Zoom to Extents mode is switched on or off:

On — The whole drawing is exported (using its extents) and scaled to fit the output .pdf page size. The user can set the page size and other page parameters directly.
Off — Page setup parameters are taken from the layout's properties and can be customized (for example, using a Page Setup dialog).

Export Layers

Layers in the original drawing can be visible (switched on) or hidden (switched off). To enable processing of layers during the export to PDF, the Enable Layers Support flag must be switched on. Also, the user can control the export of invisible layers using the Include Invisible Layers flag.

Enable Layers Support — If off, only visible geometry is exported from the drawing, and the resulting .pdf file has no layers. The Include Invisible Layers flag value is ignored. If on, layers are exported to the .pdf file, and the list of exported layers depends on the value of the Include Invisible Layers flag.
Include Invisible Layers — If on, all layers are exported, and the .pdf file contains the same quantity of layers as the original drawing (hidden layers are also exported). In other words, a fully identical copy of the layers is created in PDF format. If off, only visible layers are exported, and the resulting .pdf file doesn't contain hidden layers.

Note that exporting layers depends on the rendering mode of the original drawing: if it is rendered in wireframe mode (with or without the hidden lines removal algorithm), the output PDF document also contains layers (if Enable Layers Support is switched on of course). For other rendering modes, layer export is not supported because the content is exported as an image.

Geometry Optimization

The Use Geometry Optimization flag determines whether simple geometry optimization is used when a drawing is exported to a .pdf file. Simple geometry optimization uses a more effective mechanism of drawing document elements (drawing one polyline instead of several separated segments, Bezier curve control points, and so on). For example, if optimization is not used, a rectangle is drawn with four commands: one for each line. When optimization is used, a rectangle is drawn with a single command, thus reducing the overall size of the output file.

Export Fonts

There are three font types that can be used for text:

TrueType fonts — Fonts used on Microsoft® Windows® platforms.
SHX fonts — Internal font format for .dwg files.
RSC fonts — Fonts for .dgn files.

Text from the original drawing can be exported to PDF either with geometry (when symbols are drawn as collections of primitives) or with internal facilities of the PDF format. The TTF Text as Geometry flag enables True Type font text to geometry conversion (when switched on), and the SHX Text as Geometry flag enables SHX font text to geometry conversion. These flags can affect the size of the output .pdf file. The effect depends on the quantity of text elements in the source database.

Additionally, a font file can be included in the output .pdf file or the document may contain only a reference to a font file. In the first case a font is called embedded, and the text can be drawn even if the specified font is not installed for the operating system. In the second case the font must be installed on the operating system for the correct text to display in the output .pdf file. If the Use Embedded TTF flag is on, embedded fonts are used for text display. Using embedded fonts causes a large increase of output file size but guarantees that the text can be correctly displayed in the resulting .pdf file. Using embedded fonts also makes the output .pdf file more portable.

The Embedded TTF Optimization flag reduces the size of the output .pdf file by removing unused parts of the fonts (for example, characters that are never used in the text). However, embedded font optimization restricts editing abilities.

For additional information about handling fonts, see Font Handling.

Export Hatches

There are three kinds of hatches (as you can see in the picture below):

Solid hatch — A hatch with a one-color solid fill.
Gradient hatch — A hatch filled with one or two gradient colors.
Pattern hatch — A hatch filled with a specified pattern.

Export operations can differ depending on what kind of hatch is exported.

There are three ways of exporting hatches to PDF (using the ExportHatchesType enumerator):

PDF path (recommended, corresponds to kPdfPaths enumerator value) — Results in a smaller .pdf file size than other methods and avoids distortion of graphical elements. This algorithm exports only the outer loop of the hatch and then fills this loop with the appropriate color.
Vectorizer (corresponds to kDrawing enumerator value) — Divides the hatch into many triangles; each can contain its own color. This leads to a larger output file size.
Bitmap export (corresponds to kBitmap enumerator value) — Realizes hatches as a bitmap picture. The result of exporting a hatch as a bitmap looks smoother than as a vectorizer and often has a smaller output file size. The output file size strongly depends on the DPI (Dots Per Inch) resolution specified for the export process. Increasing DPI provides better quality but a larger output file.
To retrieve the current resolution used for exporting hatches as a bitmap, call the hatchDPI() method of the PDFExportParams class.
To change the resolution, use the setHatchDPI() method of the PDFExportParams class.

The PDF path export algorithm can be applied only to solid hatches, not gradient or pattern hatches. In those cases, bitmap export is automatically applied.

To get the current type of solid hatch for exporting, use the solidHatchesExportType() method of the PDFExportParams class. To set a new type of solid hatch for exporting, use the setSolidHatchesExportType() method of the PDFExportParams class.

Bitmap and vectorizer export can be applied to hatches of any type.

To get the current type of gradient hatch for exporting, use the gradientHatchesExportType() method of the PDFExportParams class. To set a new type of gradient hatch for exporting, use the setGradientHatchesExportType() method of the PDFExportParams class.

To get the current type of pattern hatch for exporting, use the otherHatchesExportType() method of the PDFExportParams class. To set a new type of pattern hatch for exporting, use the setOtherHatchesExportType() method of the PDFExportParams class.

The quality of exported hatches for vectorizer and PDF path export types depends on the resolution (DPI) used for vectorizing.

To get the current vectorizer resolution, use the getGeomDPI() method of the PDFExportParams class. To set a new vectorizer resolution, use the setOtherGeomDPI() method of the PDFExportParams class.

Use Data Compression and Hexadecimal Format

The Data Compression flag determines whether data compression is used during PDF export. If the flag is on, internal PDF compression algorithm is used. Data compression reduces the size of the output .pdf file.

Also, drawing data can be written in the .pdf file stream in hexadecimal format. If you do so, you can then explore the output file with hex-editors. For hexadecimal support, switch on the Hexadecimal Encoding parameter.

Remember that using hexadecimal support leads to doubling of the output file size.

Export to a Monochrome or Grayscale .pdf File

You can export an original drawing to a monochrome or grayscale .pdf file by setting the color policy of the PDFExportParams class.

The color policy can be set with the method setColorPolicy(). To retrieve the current color policy, use the colorPolicy() method.

To represent the color policy, the ColorPolicy enumeration is used:

kNoPolicy — No color policy is used. A drawing is exported with its native color palette (as is). This is the default value.
kMono — Drawing is exported to a monochrome .pdf file.
kGrayscale — Drawing is exported to a grayscale .pdf file. Native colors are converted into grayscale.

A monochrome .pdf file can also be produced by setting a monochrome plot style to the layout of the original drawing. This converts a colored drawing into a monochrome .pdf file.

A plot style is a file containing rules that determine how the colors of a drawing should be converted, in this case into monochrome, i.e. which gray gradient each color must be replaced with. To export to monochrome, specify the path to the plot style file(s) so the export program can access them.

The path to a monochrome plot style file can be set via the DDPLOTSTYLEPATHS system variable, and then the plot style can be applied to one of the drawing layouts:


bool bMonochrome(false); 
// Validator creates stylesheets equal to .ctb, .stb files. It's fully depends on DDPLOTSTYLEPATHS env var.
OdDbPlotSettingsValidatorPtr pValidator = svcs.plotSettingsValidator();

// Get database plot style mode: color-dependent or named
int i = pDb->getPSTYLEMODE();
OdString strMono((i == 1) ? "monochrome.ctb" : "monochrome.stb");
if(bMonoPalette)
{
  OdArray <const OdChar*> PSSlist ;
  pValidator->plotStyleSheetList(PSSlist);

  unsigned int iSize = PSSlist.size();
  if (iSize == 0)
  {
    STD(cout) << "Monochrome mode required files: monochrome.ctb, monochrome.stb to be found. Now exiting." << STD(endl);
    return 2;
  }

  const OdChar* mono = strMono.c_str();
  for(unsigned int i = 0; i < iSize; ++i)
  {
    if (*mono == *PSSlist[i])
    {
      bMonochrome = true;
      break;
    }
  }
}

if (bMonochrome)
{
  OdDbDictionaryPtr pLayoutDict = pDb->getLayoutDictionaryId().safeOpenObject();
  for(unsigned f=0; f < params.layouts().size(); ++f)
  {
    OdDbLayoutPtr pLayout = pLayoutDict->getAt(params.layouts()[f]).safeOpenObject(OdDb::kForWrite);
    pValidator->setCurrentStyleSheet((OdDbPlotSettings*)pLayout, strMono);
  }
}

Also, the resolution of the monochrome images for the output .pdf file can be specified; the setBWImagesDPI() method is used to set the resolution, and bwImagesDPI() is used to get the current resolution.

Exporting a drawing to a monochrome or grayscale .pdf file using plot styles has several disadvantages:

When using plot styles, there is a dependency on color-dependent or named plot style mode, which is applied to the original drawing; therefore, it is not possible to guarantee a successful export.
A plot style file (.ctb) can be missing.
A plot style cannot be applied to some types of entities (pictures, underlays, OLE objects, some types of hatches). This can lead to confusing results (as illustrated in the picture below):
Plot styles are supported for ODA Drawings (.dwg files) but can be unsupported for other ODA products and formats.
Export to monochrome mode is not supported on non-Windows platforms.

PRC Support

ODA Platform supports exporting 3D entities to 3D PDF format (PRC format). PRC support can be handled with the PRCMode() and setPRCMode() methods of the PDFExportParams class.

The value returned by PRCMode() or passed to setPRCMode() is a value of the PRCSupport enumeration:

kDisabled (0) — Export to PRC is disabled.
kAsBrep (1) — Export to PRC is supported as a B-Rep.
kAsMesh (2) — Export to PRC is supported as a mesh.

Note that you cannot turn on PRC support mode and use hidden lines removal algorithm (HLR) at the same time.

PRC data can be exported using a compression algorithm. To set the compression level, use the setPRCCompression() method. This method accepts three parameters:

compressionLevel — Determines what kind of compression algorithm is applied during the export process.
bCompressBrep — A flag that controls compression of B-Rep data. If the value is equal to true, the data is compressed.
bCompressTessellation — A flag that controls compression of tessellation data. If the value is equal to true, the data is compressed.

The compression level parameter can be one of the following values:

kA3DLooseCompression (0) — Compression with 0.001 mm tolerance.
kA3DMeddiumCompression (1) — Compression with 0.01 mm tolerance.
kA3DHighCompression (2) — Compression with 0.1 mm tolerance.

To get the current state of the compression option for PRC data, use the PRCCompression() method.

Note that this method doesn't return compression flags for B-Rep and tessellation data. It returns only the current compression level value. Therefore, be sure to set the B-Rep and (or) tessellation flags to the appropriate values before executing the export process.

To check whether the compression algorithm is used for B-Rep and tessellation data, use the hasPrcBrepCompression() and hasPrcTessellationCompression() methods of the PDFExportParams class respectively.

A PRC export context is represented by the OdPrcContextForPdfExport class, derived from OdRxObject. This class contains:

User defined data, which can be used during export to a .prc stream of a .pdf file.
Method shouldExportAsPRC(), which determines whether a specified graphical object should be rendered as .prc data in the output .pdf file. Default implementation returns false.

The OdPrcContextForPdfExport class is declared and defined in /Kernel/Exports/PdfExport/Include/PrcContextForPdfExport.h.

ODA Platform provides several types of PRC contexts, as described in the following table.

PRC Context Name	Function for Creating Context	Description
`OdPrcContextForPdfExport_AllInSingleView`	`odCreatePrcAllInSingleViewContextForTD()`	Implements single view mode: exports all entities located in one view of a drawing database into a .prc stream of the output .pdf file.
`OdPrcContextForPdfExport_OnlySolidsMultiView`	`odCreatePrcOnlySolidsMultiViewContextForTD()`	Implements one view per solid entity mode: exports each solid entity located in an individual view into a .prc stream of the output .pdf file; 2D geometry is exported into .pdf content.
`OdPrcContextForPdfExport_OnlySolidsSingleView`	`odCreatePrcOnlySolidsSingleViewContextForTD()`	Implements single view for solids mode: exports all solid entities located in one view into a .prc stream of the output .pdf file. 2D geometry is exported into .pdf content.
`OdPrcContextForPdfExport_Default`	`odCreatePrcDefaultContextForTD()`	Implements one view per entity mode: exports each entity located in an individual view into a .prc stream of the output .pdf file.
`OdPrcContextForPdfExport_AllInSingleView_DGN`	`odCreatePrcAllInSingleViewContextForDGN()`	Implements one view per entity mode for .dgn files: exports all entities located in one view of a drawing database into a .prc stream of the output .pdf file.

Functions for .dwg drawings are defined in the /Prc/Export/PrcExport/Include/PrcContextForPdfExportImpl.h header file.

Functions for .dgn drawings are defined in the /Prc/Export/Dgn2PrcExport/Include/PrcContextForPdfExportImpl.h header file.

Each type of PRC context is implemented as a successor of the OdPrcContextForPdfExport class. Each PRC context sub-class has its own implementation of the shouldExportAsPRC() method to define whether an entity should be exported into a .prc stream and to determine the viewport's index for it. PRC context sub-classes are registered in the ODA environment while creating an instance of PrcExportModule (for .dwg files) or OdDgn2PrcExportModule (for .dgn files).

To get the current PRC context containing user PRC data that should be used for the export process, call the getPRCContext() method. To set a new PRC context, use the setPRCContext() method.

PDF export functionality allows you to set a background color for PRC data created within the export process. By default, PRC data has a white background color. To set a new background color, use the setPrcBackground() method of the PDFExportParams class.

The PDFExportParams class also provides methods that allow managing the background color:

hasPrcBackground() — Determines whether the PRC data has a background color that differs from the default value (white).
getPrcBackground() — Retrieves the currently applied PRC background color.
clearPrcBackground() — Changes the current PRC background color to the default value (white).

Note: According to ISO standards, the PDF/A format is not compatible with the PRC format. Therefore, if both modes (PRC and PDF/A support) are switched on, an exInternalError occurs. See the PDF/A Format Support section for details about exporting with PDF/A support.

Export to a Linearized .pdf File

Any .pdf file can be partly processed. This means that it is possible to retrieve any portion of bytes from a file to process any particular element (for example, page, link or picture) without downloading and reading other elements of the document.

This technology for .pdf files is similar to streaming audio or video and is called linearization. It provides fast incremental access to .pdf data. Linearization has the following advantages:

Fast downloading and rendering of a .pdf document even for slow connections and big files (skips unnecessary parts when reading data).
Quick navigation through the document.
Quick application of embedded fonts.
Fast reaction to user actions (for example, clicking a link) without waiting for the entire page to be processed.

To obtain these advantages, a .pdf file should be saved using the linearization algorithm. ODA Platform supports linearization for exporting a drawing to a .pdf file by setting the appropriate flag value.

PDF/A Format Support

PDF export functionality supports creating archive .pdf documents (PDF/A).

PDF/A is a specific version of the .pdf format for long-term archival preservation of electronic documents. This format differs from common PDF format by excluding all features that can be dangerous for long-term document storage (for example font linking, encryption, etc.).

PDF/A format is standardized by ISO. ISO requirements for viewer applications contain color management guidelines, embedded fonts support, and a user interface for reading embedded annotations.

There are several versions of PDF/A format:

PDF/A-1 — See Part 1: Use of PDF 1.4 of the ISO PDF/A standard.
PDF/A-2 — See Part 2: Use of ISO 32000-1 of the ISO PDF/A standard.
PDF/A-3 — See Part 3: Use of ISO 32000-1 with Support for Embedded Files of the ISO PDF/A standard.

The difference between PDF/A-2 and PDF/A-3 is insignificant for CAD applications, therefore ODA Platform supports only PDF/A-1 and PDF/A-2 versions.

To specify a version of PDF/A format, the PDF_A_mode enumeration from the PDFExportParams class is used.

Note: When exporting drawings into archive PDF format, it is strongly recommended to use the PDF/A-2 version for the following reasons:

PDF/A-1 version does not support layers.
PDF/A-1 version does not support transparency and the MergeControl parameter is always set to the LinesOverwrite value.
Values of real data type (for example, coordinates) cannot be greater than 32767; therefore, in some cases DPI resolution should be reduced.
Strings (including streams and stream parts) cannot have a size greater than 64 Kb. This leads to the following disadvantages:
1. Picture quality is set to the minimum value.
2. ASCII hex encoding is unavailable.
3. Flat encoding is enabled to reduce the possibility of issues during the export process.
PDF/A-1 version does not support the measuring feature.

To export to the desired version of PDF/A format, use the setArchived() method of the PDFExportParams class. To retrieve whether exporting to the archive .pdf format is enabled, and if enabled, which version of PDF/A format is used, call the archived() method of the PDFExportParams class.

There are several restrictions and disadvantages of using the .pdf archive format for export:

The current ODA Platform version does not support TTF font optimization yet, therefore the TTF font optimization flag is switched off if PDF/A support is applied.
According to ISO standards, the PDF/A format is not compatible with the PRC format. Therefore, if both modes (PRC and PDF/A support) are switched on, an error occurs. See the PRC Support section for details about exporting to a .pdf file with PRC support.
The fonts can only be embedded into a PDF/A document and this leads to an increased document size.

Use Measure Functionality in PDF Export

A drawing to be exported may include graphical entities that represent real-world objects. This means that the graphical entities contain specific information about scale and measurement units to store constant data about real-world objects and their relationship with units in user space of the output .pdf file. Such information allows CAD applications to perform measurements that yield results in the units intended by the creator of the document. According to version 1.6 of the PDF format standard, measurement data can be stored in a .pdf file.

For example, a drawing contains a line that is defined with two three-dimensional points: (1000, 1000, 0) and (1100, 1000, 0) and a rectangle around it. It is obvious that the real length of the line is 100 mm:

If you export this drawing to a .pdf file with plot scale 1:1, and then apply a measuring tool in a .pdf reader application, the length of the line is quite close to the original length, for example 99.9 mm.

However, if you use a Fit to Screen plot style for export, the length of the line in the output file has a significantly different value from the original (for example 93.05 mm). This happens because the length of the line depends on the output .pdf file's page size. To keep the correct length, use a scale coefficient to recalculate the line length after applying the resizing operation.

To achieve this, you can use the kMeasuring flag, declared in the PDFExportFlags enumerator:


PDFExportParams params;
...
params.setExportFlags(PDFExportParams::PDFExportFlags(PDFExportParams::kMeasuring));

After setting the measuring scale flag, the line length in the .pdf file is equal to or very close to the original value in the drawing.

To get better accuracy of the line length, use better resolution (DPI). For example, when accuracy is 600 dpi, the 100 mm length of the line can be converted to 99.97 mm. If you use 720 dpi or higher resolution, you will get exactly 100 mm length of the line.

Export of Shaded Viewports

ODA SDK supports a shaded rendering mode for 3D figures display. In cases when you want to export such objects in a .pdf file, you can face the issue when a rendering device used for PDF export, cannot render in shaded mode. To solve this issue the PDF export module uses the device that renders the exported drawing on the screen, but redirects the rendering output to a bitmap that is inserted into the resulted .pdf file afterward.

According to this approach, the output bitmap has a very low resolution because, on the one hand, it is necessary to be sure that the graphic device is able to draw the bitmap; on the other hand, different devices have different restrictions for the bitmap size or even for the aspect ratio when an old graphic card is used.

To get more flexible behaviour, PDF export module provides the ability to set the mode of the shaded viewport rendering into one of the following values (represented with the PDFShadedViewportExportMode enumeration):

kExportOnePiece — Export shaded viewports as one-piece bitmap image with low resolution.
kExportAsStrips — Export shaded viewports as striped images according to vector resolution (geometry DPI).
kExportAsTiles — Export shaded viewports as tiled images according to vector resolution (geometry DPI).

The two last modes assume that the viewport is rendered as a set of strips or tiles corresponded to the currently set vector resolution. The kExportOnePiece value means that the old way of rendering with creating a tiny bitmap is applied.

kExportAsStrips mode demonstrates the better performance, when viewing an output .pdf file, than the kExportAsTiles mode, but it can lead to problems with rendering on old graphics card in cases when the hardware rendering is used (for example, GLES2 rendering).

Use the shadedVpExportMode() and the setShadedVpExportMode() methods for getting and setting of the shaded viewport export options respectively.

Working with Watermarks

ODA Software provides an ability to add watermarks in the resulting PDF document created by the export process and set different options for these watermarks. You can find detailed information about this opportunity below.

Any object of the PDFExportParams class can contain an array of Watermark instances, can add new watermarks to the array, and remove all watermarks from the array. To manage watermarks, the PDFExportParams class provides the following interface:

addWatermark() — Add a new watermark object to the array of watermarks.
watermarks() — Retrieves all previously added watermarks.
clearWatermarks() — Removes all watermarks from the object.

Watermark parameters are represented with the Watermark structure that stores watermark properties:

The text of a watermark and its attributes (font name, font size, font color, opacity). Available font names are represented with the WatermarkFonts enumeration.

          
Watermark watermark;
watermark.text = L"ODA Platform";
watermark.font = Watermark::kTimesRoman; //default value - Times Roman
watermark.color = ODRGB(255, 0, 0);      //default value – black
watermark.fontSize = 24;                 //default value – 48
watermark.opacity = 75;                  //default value - 50%

Position on the page that is defined with the WatermarkPosition enumeration data type (the following pictures and code fragment illustrate how a watermark looks in each position):
- The watermark is located from left to right in the page's center (figure a).
- The watermark is located in the upper-left corner of the page (figure b).
- The watermark is located in the upper-right corner of the page (figure c).
- The watermark is located in the lower-right corner of the page (figure d).
- The watermark is located in the lower-left corner of the page (figure e).
- The watermark is located from the upper-left corner to the lower-right corner of the page (figure f).
- The watermark is located from the lower-left corner to the upper-right corner of the page (figure g).
```
          
watermark.position = Watermark:: kUpperLeftToLowerRight;
          
        
```
The position for the code fragment is represented at figure f.

A watermark can also be fitted to the page size by setting the corresponding flag from the Watermark structure. The picture below shows how the watermark looks when it is fitted to the page (depending on the position).

Figure a) illustrates a fitted watermark when it is positioned in the page center.
Figure b) illustrates a fitted watermark when it is positioned in the upper corner (left or right) of the page.
Figure c) illustrates a fitted watermark when it is positioned in the lower corner (left or right) of the page.
Figure d) illustrates a fitted watermark when it is positioned from the left-lower to the right-upper corner of the page.

The following code fragment shows how a watermark can be fitted to the page like at figure d:

      
watermark.color = ODRGB(255, 0, 0);
watermark.opacity = 75;
watermark.text = L"ODA Platform";
watermark.position = Watermark:: kUpperLeftToLowerRight;
and set the scaling option: Font size in this case will be calculated automatically.
watermark.scaleToPage = true;

Note that you can add several watermarks to the PDFExportParams object like the following code fragment illustrates:

      
PDFExportParams params;

Watermark watermark;
watermark.font = Watermark::kTimesRoman; //default value - Times Roman
watermark.color = ODRGB(255, 0, 0);      //default value – black
watermark.fontSize = 24;                 //default value – 48
watermark.opacity = 75;                  //default value - 50%
Set watermark text:
watermark.text = L"Watermark example 1";
watermark.position = Watermark::kUpperRight; //default - left to right in the page center 

//Add the first watermark
params.addWatermark(watermark);

//Change the options of the watermark
watermark.color = ODRGB(0, 0, 255);
watermark.opacity = 50;
watermark.text = L"Scaled watermark example";
watermark.position = Watermark:: kUpperLeftToLowerRight;

//set the scaling option: Font size in this case will be calculated automatically.
watermark.scaleToPage = true;


//Add the second watermark:
params.addWatermark(watermark);

The resulted .pdf file is shown in the picture below:

In the OdaMfcApp sample application, you can specify watermark options for PDF export using the Export to PDF dialog:

Click Custom properties to open the additional export options dialog:

In the Watermark section, specify the watermark text, text font, font size, text color, watermark position, and opacity.

Use GsCache During Export

It takes a long time to render a complex drawing that contains many entities joint in blocks. To speed up the rendering process, the GsCache option of the graphic system can be used.

Since the ODA SDK 2021.8 version, the GsCache option can also be used for increasing the speed of the PDF export process as well. It significantly affects the time of the export procedure by decreasing the time from about a quarter for medium block to several times for a very complicated drawing.

To use the GsCache option for the PDF export, set the related options like in the code fragment below:


PDFExportParams params;
params.setExportFlags(PDFExportParams::kFlateCompression);
params.setUseGsCache(true);

Please pay attention to the disadvantage of GsCache option usage for exporting drawings, which contain a large number of entities not combined into blocks: use of the option, in this case, may cause the export time increase in comparison with exporting without GsCache.

Deprecated Export Flags

Do not use m_reserved1, m_reserved2, m_reserved3, or m_reserved4 flags because they are deprecated and can be changed or deleted in future versions of the ODA Platform.