- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Public Types | Public Member Functions | List of all members
pdftron::PDF::PDFRasterizer Class Reference

`#include <PDFRasterizer.h>`

## Public Types
enum | Type { e_BuiltIn, e_GDIPlus }
enum | OverprintPreviewMode { e_op_off = 0, e_op_on, e_op_pdfx_on }
enum | ColorPostProcessMode { e_postprocess_none = 0, e_postprocess_invert, e_postprocess_gradient_map, e_postprocess_night_mode }
typedef void(* | ErrorReportProc )(const char *message, void *data)

## Public Member Functions
| PDFRasterizer (Type type=e_BuiltIn)
| ~PDFRasterizer ()
std::vector< unsigned char > | Rasterize (Page &page, int width, int height, int stride, int num_comps, bool demult, const Common::Matrix2D &device_mtx, const Rect *clip=0, const Rect *scrl_clip_regions=0, bool *cancel=0)
void | Rasterize (Page &page, UChar *in_out_image_buffer, int width, int height, int stride, int num_comps, bool demult, const Common::Matrix2D &device_mtx, const Rect *clip=0, const Rect *scrl_clip_regions=0, bool *cancel=0)
std::vector< Separation > | RasterizeSeparations (Page &page, int width, int height, const Common::Matrix2D &mtx, const Rect *clip, volatile bool *cancel)
void | Rasterize (Page &page, void *hdc, const Common::Matrix2D &device_mtx, const Rect *clip=0, int dpi=-1, bool *cancel=0)
void | SetDrawAnnotations (bool render_annots)
void | SetHighlightFields (bool highlight_fields)
void | SetDrawUIElements (bool draw_ui_elements)
void | SetAntiAliasing (bool enable_aa)
void | SetPathHinting (bool enable_hinting)
void | SetThinLineAdjustment (bool pixel_grid_fit, bool stroke_adjust)
void | SetThinLineScaling (double scaling)
void | SetNightModeTuning (double contrast, double saturation, double flipness)
void | SetImageSmoothing (bool smoothing_enabled=true, bool hq_image_resampling=false)
void | SetCaching (bool enabled=true)
void | SetGamma (double expgamma)
void | SetOCGContext (OCG::Context *ctx)
void | SetPrintMode (bool is_printing)
void | SetOverprint (OverprintPreviewMode op)
void | SetErrorReportProc (ErrorReportProc error_proc, void *data)
void | SetRasterizerType (Type type)
Type | GetRasterizerType ()
void | SetColorPostProcessMode (ColorPostProcessMode mode)
ColorPostProcessMode | GetColorPostProcessMode () const
void | UpdateBuffer ()
void | Destroy ()

## Detailed Description

PDFRasterizer is a low-level PDF rasterizer.

The main purpose of this class is to convert PDF pages to raster images (or bitmaps).

Note
  PDFRasterizer is a relatively low-level class. If you need to convert PDF page to an image format or a Bitmap, consider using PDF::PDFDraw. Similarly, if you are building an interactive PDF viewing application you may want to use PDF::PDFView instead.

Definition at line 85 of file PDFRasterizer.h.

## Member Typedef Documentation

typedef void(* pdftron::PDF::PDFRasterizer::ErrorReportProc)(const char *message, void *data)

Error handling. A type of callback function (or a delegate in .NET terminology) that is called in case an error is encountered during rendering.

Definition at line 423 of file PDFRasterizer.h.

## Member Enumeration Documentation

enum pdftron::PDF::PDFRasterizer::ColorPostProcessMode

ColorPostProcessMode is used to modify colors after rendering.

Enumerator
e_postprocess_none |
e_postprocess_invert |
e_postprocess_gradient_map |
e_postprocess_night_mode |

Definition at line 461 of file PDFRasterizer.h.

enum pdftron::PDF::PDFRasterizer::OverprintPreviewMode

Determines if overprint is used. e_op_on: overprint is always on; e_op_off: overprint is always off. e_op_pdfx_on: overprint is on only for PDF/X files.

Enumerator
e_op_off |
e_op_on |
e_op_pdfx_on |

Definition at line 114 of file PDFRasterizer.h.

enum pdftron::PDF::PDFRasterizer::Type

PDFNet includes two separate rasterizer implementations utilizing different graphics libraries.

The default rasterizer is 'e_BuiltIn' which is a high-quality, anti-aliased and platform independent rasterizer. This rasterizer is available on all supported platforms.

On Windows platforms, PDFNet also includes GDI+ based rasterizer. (deprecated and will be removed in a future version of PDFNet) This rasterizer is included mainly to provide vector output for printing, for EMF/WMF export, etc. For plain image rasterization we recommend using the built-in rasterizer.

Enumerator
e_BuiltIn | high-quality, platform independent rasterizer.
e_GDIPlus | GDI+ based rasterizer. (Deprecated)

Definition at line 103 of file PDFRasterizer.h.

## Constructor & Destructor Documentation

pdftron::PDF::PDFRasterizer::PDFRasterizer | ( | Type | type = `e_BuiltIn` | ) |

PDFRasterizer constructor and destructor

pdftron::PDF::PDFRasterizer::~PDFRasterizer | ( |  | ) |

## Member Function Documentation

void pdftron::PDF::PDFRasterizer::Destroy | ( |  | ) |

Frees the native memory of the object.

ColorPostProcessMode pdftron::PDF::PDFRasterizer::GetColorPostProcessMode | ( |  | ) | const

Returns
  the current color post processing mode.

Type pdftron::PDF::PDFRasterizer::GetRasterizerType | ( |  | ) |

Returns
  the type of current rasterizer.

Note
  This method is deprecated, since the GDI+ rasterizer itself is deprecated and will be removed in a future version of PDFNet. It is strongly recommended to use the built-in rasterizer and to use the XPS print path where vector conversion is needed.

std::vector<unsigned char> pdftron::PDF::PDFRasterizer::Rasterize | ( | Page & | page,
|  | int | width,
|  | int | height,
|  | int | stride,
|  | int | num_comps,
|  | bool | demult,
|  | const Common::Matrix2D & | device_mtx,
|  | const Rect * | clip = `0`,
|  | const Rect * | scrl_clip_regions = `0`,
|  | bool * | cancel = `0`
| ) |  |

Draws the page into a given memory buffer.

Note
  This method is available on all platforms and in all rasterizer implementations.

Parameters

  page | The page to rasterize.
  in_out_image_buffer | A pointer to a memory buffer. The buffer must contain at least (stride * height) bytes.
  width | The width of the target image in pixels.
  height | The height of the target image in pixels (the number of rows).
  stride | Stride determines the physical width (in bytes) of one row in memory. If this value is negative the direction of the Y axis is inverted. The absolute value of stride is of importance, because it allows rendering in buffers where rows are padded in memory (e.g. in Windows bitmaps are padded on 4 byte boundaries). Besides allowing rendering on the whole buffer stride parameter can be used for rendering in a rectangular subset of a buffer.
  num_comps | The number (4 or 5) representing the number of color components in the device color space. For BGR+Alpha set this parameter to 4, and for CMYK+Alpha use 5. If other values are set, exceptions will be thrown.
  demult | - Specifies if the alpha is de-multiplied from the resulting color components.
  device_mtx | Device transformation matrix that maps PDF page from PDF user space into device coordinate space (e.g. pixel space). PDF user space is represented in page units, where one unit corresponds to 1/72 of an inch.
  clip | Optional parameter defining the clip region for the page. If the parameter is null or is not specified, PDFRasterizer uses page's crop box as a default clip region.
  scrl_clp_regions | Optional parameter reserved for a future use.
  cancel | An optional variable that can be used to stop the rendering thread.

Sample code:

* float drawing_scale = 2:
* Common::Matrix2D mtx(drawing_scale, 0, 0, drawing_scale, 0, 0);
* PDF::Rect bbox(page.GetMediaBox());
* bbox.Normalize();
* int width = int(bbox.Width() * drawing_scale);
* int height = int(bbox.Height() * drawing_scale);
*
* // Stride is represented in bytes and is aligned on 4 byte
* // boundary so that you can render directly to GDI bitmap.
* // A negative value for stride can be used to flip the image
* // upside down.
* int comps = 4; // for BGRA
* int stride = ((width * comps + 3) / 4) * 4;
*
* // buf is a memory buffer containing at least (stride*height) bytes.
* memset(ptr, 0xFF, height*stride); // Clear the background to opaque white paper color.
*
* PDFRasterizer rast;
* rast.Rasterize(page, buf, width, height, stride, 4, false, mtx);
*

void pdftron::PDF::PDFRasterizer::Rasterize | ( | Page & | page,
|  | UChar * | in_out_image_buffer,
|  | int | width,
|  | int | height,
|  | int | stride,
|  | int | num_comps,
|  | bool | demult,
|  | const Common::Matrix2D & | device_mtx,
|  | const Rect * | clip = `0`,
|  | const Rect * | scrl_clip_regions = `0`,
|  | bool * | cancel = `0`
| ) |  |

void pdftron::PDF::PDFRasterizer::Rasterize | ( | Page & | page,
|  | void * | hdc,
|  | const Common::Matrix2D & | device_mtx,
|  | const Rect * | clip = `0`,
|  | int | dpi = `-1`,
|  | bool * | cancel = `0`
| ) |  |

Draws the contents of the page to a given device context.

This method can be used to send raster or GDI output to arbitrary Windows device context (e.g. memory bitmap device, printer device, or EMF/WMF record).

See also PDF::PDFDraw::DrawInRect()

Note
  this method is only supported on Windows platforms. If your application is running on a Windows platform, you can select GDI+ rasterizer with SetRasterizerType() and e_GDIPlus type.

Parameters

  page | The page to rasterize.
  hdc | Device context (i.e. HDC structure).
  device_mtx | Device transformation matrix that maps PDF page from PDF user space into device coordinate space (e.g. pixel space). PDF user space is represented in page units, where one unit corresponds to 1/72 of an inch.
  clip | Optional parameter defining the clip region for the page. In the parameter is null or is not specified, PDFRasterizer uses page's crop box as a default clip region.
  dpi | Optional parameter used to specify the resolution of the rasterized bitmap. This parameter is used only for built-in rasterizer. If the parameter is not specified or is less than zero, PDFNet will query the target device to determine the output resolution.
  cancel | An optional variable that can be used to stop the rendering thread.

Note
  This method is deprecated, since the GDI+ rasterizer itself is deprecated and will be removed in a future version of PDFNet. It is recommended to use the built-in rasterizer via other Rasterize methods or utilize the XPS print path through Convert::ToXps or Print::StartPrintJob instead.

std::vector<Separation> pdftron::PDF::PDFRasterizer::RasterizeSeparations | ( | Page & | page,
|  | int | width,
|  | int | height,
|  | const Common::Matrix2D & | mtx,
|  | const Rect * | clip,
|  | volatile bool * | cancel
| ) |  |

Draws the page into a given memory buffer.

Note
  This method is available on all platforms and in all rasterizer implementations.

Parameters

  page | The page to rasterize.
  width | The width of the target image in pixels.
  height | The height of the target image in pixels (the number of rows).
  mtx | Device transformation matrix that maps PDF page from PDF user space into device coordinate space (e.g. pixel space). PDF user space is represented in page units, where one unit corresponds to 1/72 of an inch.
  clip | Optional parameter defining the clip region for the page. If the parameter is null or is not specified, PDFRasterizer uses page's crop box as a default clip region.
  cancel | An optional variable that can be used to stop the rendering thread.

void pdftron::PDF::PDFRasterizer::SetAntiAliasing | ( | bool | enable_aa | ) |

Enable or disable anti-aliasing.

Anti-Aliasing is a technique used to improve the visual quality of images when displaying them on low resolution devices (for example, low DPI computer monitors).

Anti-aliasing is enabled by default.

void pdftron::PDF::PDFRasterizer::SetCaching | ( | bool | enabled = `true` | ) |

Enables or disables caching. Caching can improve the rendering performance in cases where the same page will be drawn multiple times.

Parameters

  enabled | - if true PDFRasterizer will cache frequently used graphics objects.

void pdftron::PDF::PDFRasterizer::SetColorPostProcessMode | ( | ColorPostProcessMode | mode | ) |

Set the color post processing transformation. This transform is applied to the rasterized bitmap as the final step in the rasterization process, and is applied directly to the resulting bitmap (disregarding any color space information). Color post processing only supported for RGBA output.

Parameters

  mode | is the specific transform to be applied

void pdftron::PDF::PDFRasterizer::SetDrawAnnotations | ( | bool | render_annots | ) |

Enable or disable annotation and forms rendering. By default, annotations and forms are rendered.

Parameters

  render_annots | True to draw annotations, false otherwise.

void pdftron::PDF::PDFRasterizer::SetDrawUIElements | ( | bool | draw_ui_elements | ) |

Enable or disable drawing ui elements. Default is disabled.

Parameters

  draw_ui_elements | true to draw ui elements, false otherwise.

void pdftron::PDF::PDFRasterizer::SetErrorReportProc | ( | ErrorReportProc | error_proc,
|  | void * | data
| ) |  |

Sets the error handling function to be called in case an error is encountered during page rendering.

Parameters

  error_proc | Error handling callback function (or delegate in .NET)
  data | Custom data to be passed as a second parameter to 'error_proc'.

void pdftron::PDF::PDFRasterizer::SetGamma | ( | double | expgamma | ) |

Sets the gamma factor used for anti-aliased rendering.

Parameters

  expgamma | is the exponent value of gamma function. Typical values are in the range from 0.1 to 3.

Gamma correction can be used to improve the quality of anti-aliased image output and can (to some extent) decrease the appearance common anti-aliasing artifacts (such as pixel width lines between polygons).

Note
  Gamma correction is used only in the built-in rasterizer.

void pdftron::PDF::PDFRasterizer::SetHighlightFields | ( | bool | highlight_fields | ) |

Enable or disable highlighting form fields. Default is disabled.

Parameters

  highlight_fields | true to highlight, false otherwise.

void pdftron::PDF::PDFRasterizer::SetImageSmoothing | ( | bool | smoothing_enabled = `true`,
|  | bool | hq_image_resampling = `false`
| ) |  |

Enable or disable image smoothing.

The rasterizer allows a tradeoff between rendering quality and rendering speed. This function can be used to indicate the preference between rendering speed and quality.

Note
  image smoothing option has effect only if the source image has higher resolution that the output resolution of the image on the rasterized page. PDFNet automatically controls at what resolution/zoom factor, 'image smoothing' needs to take effect.

Parameters

  smoothing_enabled | True to enable image smoothing, false otherwise.
  hq_image_resampling | True to use a higher quality (but slower) smoothing algorithm image smoothing is enabled and hq_image_resampling is false.

void pdftron::PDF::PDFRasterizer::SetNightModeTuning | ( | double | contrast,
|  | double | saturation,
|  | double | flipness
| ) |  |

This setting controls the contrast, saturation and flipness of a rendered PDF when night mode is set. By default no additional tuning is done.

Parameters

  contrast | change the difference in luminance or color that makes an object distinguishable from other objects.
  saturation | change the color intensity.
  flipness | controls the inversion of colors when rendered.

Note
  values range from 0.0 to 1.0

void pdftron::PDF::PDFRasterizer::SetOCGContext | ( | OCG::Context * | ctx | ) |

Sets the Optional Content Group (OCG) context that should be used when rendering the page. This function can be used to selectively render optional content (such as PDF layers) based on the states of optional content groups in the given context.

Parameters

  ctx | Optional Content Group (OCG) context, or NULL if the rasterizer should render all content on the page.

void pdftron::PDF::PDFRasterizer::SetOverprint | ( | OverprintPreviewMode | op | ) |

Enable or disable support for overprint and overprint simulation. Overprint is a device dependent feature and the results will vary depending on the output color space and supported colorants (i.e. CMYK, CMYK+spot, RGB, etc).

By default overprint is only enabled for PDF/X files.

Parameters

  op | e_op_on: always enabled; e_op_off: always disabled; e_op_pdfx_on: enabled for PDF/X files only.

void pdftron::PDF::PDFRasterizer::SetPathHinting | ( | bool | enable_hinting | ) |

Enable or disable path hinting.

Parameters

  enable_hinting | if true path hinting is enabled. Path hinting is used to slightly adjust paths in order to avoid or alleviate artifacts of hair line cracks between certain graphical elements. This option is turned on by default.

void pdftron::PDF::PDFRasterizer::SetPrintMode | ( | bool | is_printing | ) |

Tells the rasterizer to render the page 'print' mode. Certain page elements (such as annotations or OCG-s) are meant to be visible either on the screen or on the printed paper but not both. A common example, is the "Submit" button on electronic forms.

Parameters

  is_printing | set to true is the page should be rendered in print mode. By default, print mode flag is set to false.

void pdftron::PDF::PDFRasterizer::SetRasterizerType | ( | Type | type | ) |

Sets the core graphics library used for rasterization and rendering. Using this method it is possible to quickly switch between different implementations. By default, PDFNet uses a built-in, high-quality, and platform independent rasterizer.

Parameters

  type | Rasterizer type.

Note
  This method is deprecated, since the GDI+ rasterizer itself is deprecated and will be removed in a future version of PDFNet. It is strongly recommended to use the built-in rasterizer and to use the XPS print path where vector conversion is needed.

void pdftron::PDF::PDFRasterizer::SetThinLineAdjustment | ( | bool | pixel_grid_fit,
|  | bool | stroke_adjust
| ) |  |

Set thin line adjustment parameters.

Parameters

  pixel_grid_fit | if true (horizontal/vertical) thin lines will be snapped to integer pixel positions. This helps make thin lines look sharper and clearer. This option is turned off by default and it only works if path hinting is enabled.
  stroke_adjust | if true auto stroke adjustment is enabled. Currently, this would make lines with sub-pixel width to be one-pixel wide. This option is turned on by default.

void pdftron::PDF::PDFRasterizer::SetThinLineScaling | ( | double | scaling | ) |

This setting controls the thickness of zero-width lines when rendered. In a PDF, a line width of zero denotes the thinnest line that can be rendered at device resolution: 1 device pixel wide. However, on high-resolution devices, a single pixel can be nearly invisible.

Parameters

  scaling | use this setting to increase the apparent thickness of these zero-width lines. 1.0 (1 pixel wide)

void pdftron::PDF::PDFRasterizer::UpdateBuffer | ( |  | ) |

This function is typically called for progressive rendering, in which we don't want to stop the main rendering thread. Since the rendering thread may modify separation channels, we don't consider separations in progressive rendering.

The documentation for this class was generated from the following file:

- PDF/PDFRasterizer.h