org.apache.pdfbox.rendering

## Class PDFRenderer

- java.lang.Object
- - org.apache.pdfbox.rendering.PDFRenderer

    public class PDFRenderer
    extends Object

Renders a PDF document to an AWT BufferedImage. This class may be overridden in order to perform custom rendering.

Author:
  John Hewson

### Field Summary

Fields
`protected PDDocument` `document`

### Constructor Summary

Constructors
Constructor and Description
`PDFRenderer(PDDocument document)` Creates a new PDFRenderer.

### Method Summary

All Methods Instance Methods Concrete Methods
`protected PageDrawer` `createPageDrawer(PageDrawerParameters parameters)` Returns a new PageDrawer instance, using the given parameters.
`AnnotationFilter` `getAnnotationsFilter()` Return the AnnotationFilter.
`RenderDestination` `getDefaultDestination()`
`float` `getImageDownscalingOptimizationThreshold()`
`RenderingHints` `getRenderingHints()` Get the rendering hints.
`boolean` `isGroupEnabled(PDOptionalContentGroup group)` Indicates whether an optional content group is enabled.
`boolean` `isSubsamplingAllowed()` Value indicating if the renderer is allowed to subsample images before drawing, according to image dimensions and requested scale.
`BufferedImage` `renderImage(int pageIndex)` Returns the given page as an RGB image at 72 DPI
`BufferedImage` `renderImage(int pageIndex, float scale)` Returns the given page as an RGB image at the given scale.
`BufferedImage` `renderImage(int pageIndex, float scale, ImageType imageType)` Returns the given page as an RGB or ARGB image at the given scale.
`BufferedImage` `renderImage(int pageIndex, float scale, ImageType imageType, RenderDestination destination)` Returns the given page as an RGB or ARGB image at the given scale.
`BufferedImage` `renderImageWithDPI(int pageIndex, float dpi)` Returns the given page as an RGB image at the given DPI.
`BufferedImage` `renderImageWithDPI(int pageIndex, float dpi, ImageType imageType)` Returns the given page as an RGB image at the given DPI.
`void` `renderPageToGraphics(int pageIndex, Graphics2D graphics)` Renders a given page to an AWT Graphics2D instance at 72 DPI.
`void` `renderPageToGraphics(int pageIndex, Graphics2D graphics, float scale)` Renders a given page to an AWT Graphics2D instance.
`void` `renderPageToGraphics(int pageIndex, Graphics2D graphics, float scaleX, float scaleY)` Renders a given page to an AWT Graphics2D instance.
`void` `renderPageToGraphics(int pageIndex, Graphics2D graphics, float scaleX, float scaleY, RenderDestination destination)` Renders a given page to an AWT Graphics2D instance.
`void` `setAnnotationsFilter(AnnotationFilter annotationsFilter)` Set the AnnotationFilter.
`void` `setDefaultDestination(RenderDestination defaultDestination)`
`void` `setImageDownscalingOptimizationThreshold(float imageDownscalingOptimizationThreshold)` Set the image downscaling optimization threshold.
`void` `setRenderingHints(RenderingHints renderingHints)` Set the rendering hints.
`void` `setSubsamplingAllowed(boolean subsamplingAllowed)` Sets a value instructing the renderer whether it is allowed to subsample images before drawing.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### document

    protected final PDDocument document

### Constructor Detail

#### PDFRenderer

    public PDFRenderer(PDDocument document)

Creates a new PDFRenderer.

Parameters:
  `document` - the document to render

### Method Detail

#### getAnnotationsFilter

    public AnnotationFilter getAnnotationsFilter()

Return the AnnotationFilter.

Returns:
  the AnnotationFilter

#### setAnnotationsFilter

    public void setAnnotationsFilter(AnnotationFilter annotationsFilter)

Set the AnnotationFilter.

Allows to only render annotation accepted by the filter.

Parameters:
  `annotationsFilter` - the AnnotationFilter

#### isSubsamplingAllowed

    public boolean isSubsamplingAllowed()

Value indicating if the renderer is allowed to subsample images before drawing, according to image dimensions and requested scale. Subsampling may be faster and less memory-intensive in some cases, but it may also lead to loss of quality, especially in images with high spatial frequency.

Returns:
  true if subsampling of images is allowed, false otherwise.

#### setSubsamplingAllowed

    public void setSubsamplingAllowed(boolean subsamplingAllowed)

Sets a value instructing the renderer whether it is allowed to subsample images before drawing. The subsampling frequency is determined according to image size and requested scale. Subsampling may be faster and less memory-intensive in some cases, but it may also lead to loss of quality, especially in images with high spatial frequency.

Parameters:
  `subsamplingAllowed` - The new value indicating if subsampling is allowed.

#### getDefaultDestination

    public RenderDestination getDefaultDestination()

Returns:
  the defaultDestination

#### setDefaultDestination

    public void setDefaultDestination(RenderDestination defaultDestination)

Parameters:
  `defaultDestination` - the defaultDestination to set

#### getRenderingHints

    public RenderingHints getRenderingHints()

Get the rendering hints.

Returns:
  the rendering hints or null if none are set.

#### setRenderingHints

    public void setRenderingHints(RenderingHints renderingHints)

Set the rendering hints. Use this to influence rendering quality and speed. If you don't set them yourself or pass null, PDFBox will decide at runtime depending on the destination.

Parameters:
  `renderingHints` - rendering hints to be used to influence rendering quality and speed

#### getImageDownscalingOptimizationThreshold

    public float getImageDownscalingOptimizationThreshold()

Returns:
  get the image downscaling optimization threshold. See `getImageDownscalingOptimizationThreshold()` for details.

#### setImageDownscalingOptimizationThreshold

    public void setImageDownscalingOptimizationThreshold(float imageDownscalingOptimizationThreshold)

Set the image downscaling optimization threshold. This must be a value between 0 and 1. When rendering downscaled images and rendering hints are set to bicubic+quality and the scaling is smaller than the threshold, a more quality-optimized but slower method will be used. The default is 0.5 which is a good compromise.

Parameters:
  `imageDownscalingOptimizationThreshold` - image downscaling optimization threshold

#### renderImage

    public BufferedImage renderImage(int pageIndex)
                              throws IOException

Returns the given page as an RGB image at 72 DPI

Parameters:
  `pageIndex` - the zero-based index of the page to be converted.
Returns:
  the rendered page image
Throws:
  `IOException` - if the PDF cannot be read
  `IllegalStateException` - if the requested index isn't found or doesn't point to a valid page dictionary
  `IndexOutOfBoundsException` - if the requested index is higher than the page count

#### renderImage

    public BufferedImage renderImage(int pageIndex,
                                     float scale)
                              throws IOException

Returns the given page as an RGB image at the given scale. A scale of 1 will render at 72 DPI.

Parameters:
  `pageIndex` - the zero-based index of the page to be converted
  `scale` - the scaling factor, where 1 = 72 DPI
Returns:
  the rendered page image
Throws:
  `IOException` - if the PDF cannot be read
  `IllegalStateException` - if the requested index isn't found or doesn't point to a valid page dictionary
  `IndexOutOfBoundsException` - if the requested index is higher than the page count

#### renderImageWithDPI

    public BufferedImage renderImageWithDPI(int pageIndex,
                                            float dpi)
                                     throws IOException

Returns the given page as an RGB image at the given DPI.

Parameters:
  `pageIndex` - the zero-based index of the page to be converted
  `dpi` - the DPI (dots per inch) to render at
Returns:
  the rendered page image
Throws:
  `IOException` - if the PDF cannot be read
  `IllegalStateException` - if the requested index isn't found or doesn't point to a valid page dictionary
  `IndexOutOfBoundsException` - if the requested index is higher than the page count

#### renderImageWithDPI

    public BufferedImage renderImageWithDPI(int pageIndex,
                                            float dpi,
                                            ImageType imageType)
                                     throws IOException

Returns the given page as an RGB image at the given DPI.

Parameters:
  `pageIndex` - the zero-based index of the page to be converted
  `dpi` - the DPI (dots per inch) to render at
  `imageType` - the type of image to return
Returns:
  the rendered page image
Throws:
  `IOException` - if the PDF cannot be read
  `IllegalStateException` - if the requested index isn't found or doesn't point to a valid page dictionary
  `IndexOutOfBoundsException` - if the requested index is higher than the page count

#### renderImage

    public BufferedImage renderImage(int pageIndex,
                                     float scale,
                                     ImageType imageType)
                              throws IOException

Returns the given page as an RGB or ARGB image at the given scale.

Parameters:
  `pageIndex` - the zero-based index of the page to be converted
  `scale` - the scaling factor, where 1 = 72 DPI
  `imageType` - the type of image to return
Returns:
  the rendered page image
Throws:
  `IOException` - if the PDF cannot be read
  `IllegalStateException` - if the requested index isn't found or doesn't point to a valid page dictionary
  `IndexOutOfBoundsException` - if the requested index is higher than the page count

#### renderImage

    public BufferedImage renderImage(int pageIndex,
                                     float scale,
                                     ImageType imageType,
                                     RenderDestination destination)
                              throws IOException

Returns the given page as an RGB or ARGB image at the given scale.

Parameters:
  `pageIndex` - the zero-based index of the page to be converted
  `scale` - the scaling factor, where 1 = 72 DPI
  `imageType` - the type of image to return
  `destination` - controlling visibility of optional content groups
Returns:
  the rendered page image
Throws:
  `IOException` - if the PDF cannot be read
  `IllegalStateException` - if the requested index isn't found or doesn't point to a valid page dictionary
  `IndexOutOfBoundsException` - if the requested index is higher than the page count

#### renderPageToGraphics

    public void renderPageToGraphics(int pageIndex,
                                     Graphics2D graphics)
                              throws IOException

Renders a given page to an AWT Graphics2D instance at 72 DPI.

Read `renderPageToGraphics(int, Graphics2D, float, float, RenderDestination)` before using this.

Parameters:
  `pageIndex` - the zero-based index of the page to be converted
  `graphics` - the Graphics2D on which to draw the page
Throws:
  `IOException` - if the PDF cannot be read

#### renderPageToGraphics

    public void renderPageToGraphics(int pageIndex,
                                     Graphics2D graphics,
                                     float scale)
                              throws IOException

Renders a given page to an AWT Graphics2D instance.

Read `renderPageToGraphics(int, Graphics2D, float, float, RenderDestination)` before using this.

Parameters:
  `pageIndex` - the zero-based index of the page to be converted
  `graphics` - the Graphics2D on which to draw the page
  `scale` - the scaling factor, where 1 = 72 DPI
Throws:
  `IOException` - if the PDF cannot be read

#### renderPageToGraphics

    public void renderPageToGraphics(int pageIndex,
                                     Graphics2D graphics,
                                     float scaleX,
                                     float scaleY)
                              throws IOException

Renders a given page to an AWT Graphics2D instance.

Read `renderPageToGraphics(int, Graphics2D, float, float, RenderDestination)` before using this.

Parameters:
  `pageIndex` - the zero-based index of the page to be converted
  `graphics` - the Graphics2D on which to draw the page
  `scaleX` - the scale to draw the page at for the x-axis, where 1 = 72 DPI
  `scaleY` - the scale to draw the page at for the y-axis, where 1 = 72 DPI
Throws:
  `IOException` - if the PDF cannot be read

#### renderPageToGraphics

    public void renderPageToGraphics(int pageIndex,
                                     Graphics2D graphics,
                                     float scaleX,
                                     float scaleY,
                                     RenderDestination destination)
                              throws IOException

Renders a given page to an AWT Graphics2D instance.

Known problems:

- rendering of PDF files with transparencies is not supported on Ubuntu, see PDFBOX-4581 and JDK-6689349. Rendering will not abort, but the pages will be rendered incorrectly.
- Clipping the Graphics2D will not work properly, see PDFBOX-4583.

If you encounter these problems, then you should render into an image by using the `renderImage` methods.

Parameters:
  `pageIndex` - the zero-based index of the page to be converted
  `graphics` - the Graphics2D on which to draw the page
  `scaleX` - the scale to draw the page at for the x-axis, where 1 = 72 DPI
  `scaleY` - the scale to draw the page at for the y-axis, where 1 = 72 DPI
  `destination` - controlling visibility of optional content groups
Throws:
  `IOException` - if the PDF cannot be read
  `IllegalStateException` - if the requested index isn't found or doesn't point to a valid page dictionary
  `IndexOutOfBoundsException` - if the requested index is higher than the page count

#### isGroupEnabled

    public boolean isGroupEnabled(PDOptionalContentGroup group)

Indicates whether an optional content group is enabled.

Parameters:
  `group` - the group
Returns:
  true if the group is enabled

#### createPageDrawer

    protected PageDrawer createPageDrawer(PageDrawerParameters parameters)
                                   throws IOException

Returns a new PageDrawer instance, using the given parameters. May be overridden.

Parameters:
  `parameters` - parameters to be used when creating the PageDrawer instance
Returns:
  a new PageDrawer instance
Throws:
  `IOException` - id the PageDrawer instance could not be created