pdftron::PDF::PDFRasterizer Class Reference

PDFRasterizer is a low-level PDF rasterizer. More...

#include <PDFRasterizer.h>

List of all members.

Public Types

enum  Type { e_BuiltIn, e_GDIPlus }
 PDFNet includes two separate rasterizer implementations utilizing different graphics libraries. More...
typedef void(* ErrorReportProc )(const char *message, void *data)
 Error handling.

Public Member Functions

 PDFRasterizer (Type type=e_BuiltIn)
 PDFRasterizer constructor and destructor.
 ~PDFRasterizer ()
void Rasterize (Page &page, UChar *in_out_image_buffer, int width, int height, int stride, int num_comps, const Common::Matrix2D &device_mtx, const Rect *clip=0, const Rect *scrl_clp_regions=0, volatile bool *cancel=0)
 Draws the page into a given memory buffer.
void Rasterize (Page &page, void *hdc, const Common::Matrix2D &device_mtx, const Rect *clip=0, int dpi=-1, volatile bool *cancel=0)
 Draws the contents of the page to a given device context.
void SetDrawAnnotations (bool render_annots)
 Enable or disable annotation and forms rendering.
void SetAntiAliasing (bool enable_aa)
 Enable or disable anti-aliasing.
void SetImageSmoothing (bool smoothing_enabled=true)
 Enable or disable image smoothing.
void SetCaching (bool enabled=true)
 Enables or disables caching.
void SetGamma (double exp)
 Sets the gamma factor used for anti-aliased rendering.
void SetOCGContext (OCG::Context *ctx)
 Sets the Optional Content Group (OCG) context that should be used when rendering the page.
void SetPrintMode (bool is_printing)
 Tells the rasterizer to render the page 'print' mode.
void SetOverprint (bool overprint)
 Enable or disable support for overprint and overprint simulation.
void SetErrorReportProc (ErrorReportProc error_proc, void *data)
 Sets the error handling function to be called in case an error is encountered during page rendering.
void SetRasterizerType (Type type)
 Sets the core graphics library used for rasterization and rendering.
Type GetRasterizerType ()


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.

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.


Member Enumeration Documentation

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. 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.


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::Rasterize ( Page page,
UChar in_out_image_buffer,
int  width,
int  height,
int  stride,
int  num_comps,
const Common::Matrix2D device_mtx,
const Rect clip = 0,
const Rect scrl_clp_regions = 0,
volatile 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 (2, 4, or 5) representing the number of color components in the device color space. For grayscale output set this parameter to 2 (i.e. Gray+Alpha), for RGB+Alpha use 4, and for CMYK+Alpha use 5.
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.
Note:
By default, the pixel format for rendering buffer is BGR (Blue-Green-Red).
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, comps, mtx);

void pdftron::PDF::PDFRasterizer::Rasterize ( Page page,
void *  hdc,
const Common::Matrix2D device_mtx,
const Rect clip = 0,
int  dpi = -1,
volatile 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.

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::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::SetImageSmoothing ( bool  smoothing_enabled = true  ) 

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. image smoothing is enabled.

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::SetGamma ( double  exp  ) 

Sets the gamma factor used for anti-aliased rendering.

Parameters:
exp 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::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::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::SetOverprint ( bool  overprint  ) 

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 simulation is enabled.

Parameters:
overprint If true, overprint support will be enabled. If false, overprint support will be disabled.

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::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.

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

Returns:
the type of current rasterizer.


© 2002-2010 PDFTron Systems Inc.