All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
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< SeparationRasterizeSeparations (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 SetAntiAliasing (bool enable_aa)
 
void SetPathHinting (bool enable_hinting)
 
void SetThinLineAdjustment (bool pixel_grid_fit, bool stroke_adjust)
 
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 378 of file PDFRasterizer.h.

Member Enumeration Documentation

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 416 of file PDFRasterizer.h.

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.

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
pageThe page to rasterize.
in_out_image_bufferA pointer to a memory buffer. The buffer must contain at least (stride * height) bytes.
widthThe width of the target image in pixels.
heightThe height of the target image in pixels (the number of rows).
strideStride 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_compsThe 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_mtxDevice 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.
clipOptional 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_regionsOptional parameter reserved for a future use.
cancelAn 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.
*
* 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
pageThe page to rasterize.
hdcDevice context (i.e. HDC structure).
device_mtxDevice 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.
clipOptional 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.
dpiOptional 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.
cancelAn 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 
)
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
modeis 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_annotsTrue to draw annotations, 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_procError handling callback function (or delegate in .NET)
dataCustom 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
expgammais 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_fieldstrue 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_enabledTrue to enable image smoothing, false otherwise.
hq_image_resamplingTrue to use a higher quality (but slower) smoothing algorithm image smoothing is enabled and hq_image_resampling is false.
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
ctxOptional 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
ope_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_hintingif 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_printingset 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
typeRasterizer 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_fitif 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_adjustif 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::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: