PTPDFRasterizer

@interface PTPDFRasterizer : NSObject

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.
  • PDFRasterizer constructor and destructor

    Declaration

    Objective-C

    - (instancetype)initWithType:(PTRasterizerType)type;

    Swift

    init!(type: PTRasterizerType)
  • Undocumented

    Declaration

    Objective-C

    - (NSData*)Rasterize: (PTPage*)page width:  (int)width height:  (int)height stride:  (int)stride num_comps:  (int)num_comps demult:  (BOOL)demult device_mtx:  (PTMatrix2D*)device_mtx clip:  (PTPDFRect*)clip scrl_clip_regions:  (PTPDFRect*)scrl_clip_regions;

    Swift

    func rasterize(_ page: PTPage!, width: Int32, height: Int32, stride: Int32, num_comps: Int32, demult: Bool, device_mtx: PTMatrix2D!, clip: PTPDFRect!, scrl_clip_regions: PTPDFRect!) -> Data!
  • Draws the page into a given memory buffer.

    Note

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

    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);
    

    Declaration

    Objective-C

    - (NSMutableArray *)RasterizeSeparations:(PTPage *)page
                                       width:(int)width
                                      height:(int)height
                                         mtx:(PTMatrix2D *)mtx
                                        clip:(PTPDFRect *)clip
                                      cancel:(BOOL *)cancel;

    Swift

    func rasterizeSeparations(_ page: PTPage!, width: Int32, height: Int32, mtx: PTMatrix2D!, clip: PTPDFRect!, cancel: UnsafeMutablePointer<ObjCBool>!) -> NSMutableArray!

    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.

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

    Declaration

    Objective-C

    - (void)SetDrawAnnotations:(BOOL)render_annots;

    Swift

    func setDrawAnnotations(_ render_annots: Bool)

    Parameters

    render_annots

    True to draw annotations, false otherwise.

  • Enable or disable highlighting form fields. Default is disabled.

    Declaration

    Objective-C

    - (void)SetHighlightFields:(BOOL)highlight_fields;

    Swift

    func setHighlightFields(_ highlight_fields: Bool)

    Parameters

    highlight_fields

    true to highlight, false otherwise.

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

    @default Anti-aliasing is enabled by default.

    Declaration

    Objective-C

    - (void)SetAntiAliasing:(BOOL)enable_aa;

    Swift

    func setAntiAliasing(_ enable_aa: Bool)
  • Enable or disable path hinting.

    Declaration

    Objective-C

    - (void)SetPathHinting:(BOOL)enable_hinting;

    Swift

    func setPathHinting(_ enable_hinting: Bool)

    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.

  • Set thin line adjustment parameters.

    Declaration

    Objective-C

    - (void)SetThinLineAdjustment:(BOOL)pixel_grid_fit
                    stroke_adjust:(BOOL)stroke_adjust;

    Swift

    func setThinLineAdjustment(_ pixel_grid_fit: Bool, stroke_adjust: Bool)

    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.

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

    Declaration

    Objective-C

    - (void)SetImageSmoothing:(BOOL)smoothing_enabled
          hq_image_resampling:(BOOL)hq_image_resampling;

    Swift

    func setImageSmoothing(_ smoothing_enabled: Bool, hq_image_resampling: Bool)

    Parameters

    smoothing_enabled

    True to enable image smoothing, false otherwise.

    hq_image_resampling

    True to use a higher quality (but slower) smoothing algorithm @default image smoothing is enabled and hq_image_resampling is false.

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

    Declaration

    Objective-C

    - (void)SetCaching:(BOOL)enabled;

    Swift

    func setCaching(_ enabled: Bool)

    Parameters

    enabled

    - if true PDFRasterizer will cache frequently used graphics objects.

  • Sets the gamma factor used for anti-aliased rendering.

    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.

    Declaration

    Objective-C

    - (void)SetGamma:(double)expgamma;

    Swift

    func setGamma(_ expgamma: Double)

    Parameters

    expgamma

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

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

    Declaration

    Objective-C

    - (void)SetOCGContext:(PTContext *)ctx;

    Swift

    func setOCGContext(_ ctx: PTContext!)

    Parameters

    ctx

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

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

    Declaration

    Objective-C

    - (void)SetPrintMode:(BOOL)is_printing;

    Swift

    func setPrintMode(_ is_printing: Bool)

    Parameters

    is_printing

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

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

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

    Declaration

    Objective-C

    - (void)SetOverprint:(PTOverprintPreviewMode)op;

    Swift

    func setOverprint(_ op: PTOverprintPreviewMode)

    Parameters

    op

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

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

    Declaration

    Objective-C

    - (void)SetErrorReportProc:(PTCallback *)instance;

    Swift

    func setErrorReportProc(_ instance: PTCallback!)

    Parameters

    error_proc

    Error handling callback function (or delegate in .NET)

    data

    Custom data to be passed as a second parameter to ‘error_proc’.

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

    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.

    Declaration

    Objective-C

    - (void)SetRasterizerType:(PTRasterizerType)type;

    Swift

    func setRasterizerType(_ type: PTRasterizerType)

    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.

    Declaration

    Objective-C

    - (PTRasterizerType)GetRasterizerType;

    Swift

    func getType() -> PTRasterizerType

    Return Value

    the type of current rasterizer.

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

    Declaration

    Objective-C

    - (void)SetColorPostProcessMode:(PTColorPostProcessMode)mode;

    Swift

    func setColorPostProcessMode(_ mode: PTColorPostProcessMode)

    Parameters

    mode

    is the specific transform to be applied

  • Declaration

    Objective-C

    - (PTColorPostProcessMode)GetColorPostProcessMode;

    Swift

    func getColorPostProcessMode() -> PTColorPostProcessMode

    Return Value

    the current color post processing mode.

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

    Declaration

    Objective-C

    - (void)UpdateBuffer;

    Swift

    func updateBuffer()