Struct pdfium_render::render_config::PdfRenderConfig

pub struct PdfRenderConfig { /* private fields */ }

Configures the scaling, rotation, and rendering settings that should be applied to a PdfPage to create a PdfBitmap for that page. PdfRenderConfig can accommodate pages of different sizes while correctly maintaining each page’s aspect ratio, automatically rotate portrait or landscape pages, generate page thumbnails, apply maximum and minimum pixel sizes to the scaled width and height of the final bitmap, highlight form fields with different colors, apply custom transforms to the page during rendering, and set internal Pdfium rendering flags.

Pdfium’s rendering pipeline supports either rendering with form data or rendering with a custom transformation matrix, but not both at the same time. Applying any transformation automatically disables rendering of form data. If you must render form data while simultaneously applying transformations, consider using the PdfPage::flatten() function to flatten the form elements and form data into the containing page.

Implementations

impl PdfRenderConfig

pub fn new() -> Self

Creates a new PdfRenderConfig object with all settings initialized with their default values.

pub fn thumbnail(self, size: Pixels) -> Self

Applies settings suitable for generating a thumbnail.

• The source PdfPage will be rendered with a maximum width and height of the given pixel size.
• The page will not be rotated, irrespective of its orientation.
• Image quality settings will be reduced to improve performance.
• Annotations and user-filled form field data will not be rendered.

These settings are applied to this PdfRenderConfig object immediately and can be selectively overridden by later function calls. For instance, a later call to PdfRenderConfig::rotate() can specify a custom rotation setting that will apply to the thumbnail.

pub fn set_target_size(self, width: Pixels, height: Pixels) -> Self

Converts the width and height of a PdfPage from points to pixels, scaling each dimension to the given target pixel sizes. The aspect ratio of the source page will not be maintained.

pub fn set_target_width(self, width: Pixels) -> Self

Converts the width of a PdfPage from points to pixels, scaling the source page width to the given target pixel width. The aspect ratio of the source page will be maintained so long as there is no call to PdfRenderConfig::set_target_size() or PdfRenderConfig::set_target_height() that overrides it.

pub fn set_target_height(self, height: Pixels) -> Self

Converts the height of a PdfPage from points to pixels, scaling the source page height to the given target pixel height. The aspect ratio of the source page will be maintained so long as there is no call to PdfRenderConfig::set_target_size() or PdfRenderConfig::set_target_width() that overrides it.

pub fn scale_page_to_display_size(self, width: Pixels, height: Pixels) -> Self

Applies settings to this PdfRenderConfig suitable for filling the given screen display size.

The source page’s dimensions will be scaled so that both width and height attempt to fill, but do not exceed, the given pixel dimensions. The aspect ratio of the source page will be maintained. Landscape pages will be automatically rotated by 90 degrees and will be scaled down if necessary to fit the display width.

pub fn scale_page_by_factor(self, scale: f32) -> Self

Converts the width and height of a PdfPage from points to pixels by applying the given scale factor to both dimensions. The aspect ratio of the source page will be maintained. Overrides any previous call to PdfRenderConfig::scale_page_by_factor(), PdfRenderConfig::scale_page_width_by_factor(), or PdfRenderConfig::scale_page_height_by_factor().

pub fn scale_page_width_by_factor(self, scale: f32) -> Self

Converts the width of the PdfPage from points to pixels by applying the given scale factor. The aspect ratio of the source page will not be maintained if a different scale factor is applied to the height. Overrides any previous call to PdfRenderConfig::scale_page_by_factor(), PdfRenderConfig::scale_page_width_by_factor(), or PdfRenderConfig::scale_page_height_by_factor().

pub fn scale_page_height_by_factor(self, scale: f32) -> Self

Converts the height of the PdfPage from points to pixels by applying the given scale factor. The aspect ratio of the source page will not be maintained if a different scale factor is applied to the width. Overrides any previous call to PdfRenderConfig::scale_page_by_factor(), PdfRenderConfig::scale_page_width_by_factor(), or PdfRenderConfig::scale_page_height_by_factor().

pub fn set_maximum_width(self, width: Pixels) -> Self

Specifies that the final pixel width of the PdfPage will not exceed the given maximum.

pub fn set_maximum_height(self, height: Pixels) -> Self

Specifies that the final pixel height of the PdfPage will not exceed the given maximum.

pub fn rotate(
    self,
    rotation: PdfBitmapRotation,
    do_rotate_constraints: bool
) -> Self

Applies the given clockwise rotation setting to the PdfPage during rendering, irrespective of its orientation. If the given flag is set to true then any maximum constraint on the final pixel width set by a call to PdfRenderConfig::set_maximum_width() will be rotated so it becomes a constraint on the final pixel height, and any maximum constraint on the final pixel height set by a call to PdfRenderConfig::set_maximum_height() will be rotated so it becomes a constraint on the final pixel width.

pub fn rotate_if_portrait(
    self,
    rotation: PdfBitmapRotation,
    do_rotate_constraints: bool
) -> Self

Applies the given clockwise rotation settings to the PdfPage during rendering, if the page is in portrait orientation. If the given flag is set to true and the given rotation setting is PdfBitmapRotation::Degrees90 or PdfBitmapRotation::Degrees270 then any maximum constraint on the final pixel width set by a call to PdfRenderConfig::set_maximum_width() will be rotated so it becomes a constraint on the final pixel height and any maximum constraint on the final pixel height set by a call to PdfRenderConfig::set_maximum_height() will be rotated so it becomes a constraint on the final pixel width.

pub fn rotate_if_landscape(
    self,
    rotation: PdfBitmapRotation,
    do_rotate_constraints: bool
) -> Self

Applies the given rotation settings to the PdfPage during rendering, if the page is in landscape orientation. If the given flag is set to true and the given rotation setting is PdfBitmapRotation::Degrees90 or PdfBitmapRotation::Degrees270 then any maximum constraint on the final pixel width set by a call to PdfRenderConfig::set_maximum_width() will be rotated so it becomes a constraint on the final pixel height and any maximum constraint on the final pixel height set by a call to PdfRenderConfig::set_maximum_height() will be rotated so it becomes a constraint on the final pixel width.

pub fn set_format(self, format: PdfBitmapFormat) -> Self

Sets the pixel format that will be used during rendering of the PdfPage. The default is PdfBitmapFormat::BGRA.

pub fn clear_before_rendering(self, do_clear: bool) -> Self

Controls whether the destination bitmap should be cleared by setting every pixel to a known color value before rendering the PdfPage. The default is true. The color used during clearing can be customised by calling PdfRenderConfig::set_clear_color().

pub fn set_clear_color(self, color: PdfColor) -> Self

Sets the color applied to every pixel in the destination bitmap when clearing the bitmap before rendering the PdfPage. The default is PdfColor::SOLID_WHITE. This setting has no effect if PdfRenderConfig::clear_before_rendering() is set to false.

pub fn render_form_data(self, do_render: bool) -> Self

Controls whether form data widgets and user-supplied form data should be included during rendering of the PdfPage. The default is true.

Pdfium’s rendering pipeline supports either rendering with form data or rendering with a custom transformation matrix, but not both at the same time. Applying any transformation automatically sets this value to false, disabling rendering of form data.

pub fn render_annotations(self, do_render: bool) -> Self

Controls whether user-supplied annotations should be included during rendering of the PdfPage. The default is true.

pub fn use_lcd_text_rendering(self, do_set_flag: bool) -> Self

Controls whether text rendering should be optimized for LCD display. The default is false. Has no effect if anti-aliasing of text has been disabled by a call to PdfRenderConfig::set_text_smoothing(false).

pub fn disable_native_text_rendering(self, do_set_flag: bool) -> Self

Controls whether platform text rendering should be disabled on platforms that support it. The alternative is for Pdfium to render all text internally, which may give more consistent rendering results across platforms but may also be slower. The default is false.

pub fn use_grayscale_rendering(self, do_set_flag: bool) -> Self

Controls whether rendering output should be grayscale rather than full color. The default is false.

pub fn limit_render_image_cache_size(self, do_set_flag: bool) -> Self

Controls whether Pdfium should limit its image cache size during rendering. A smaller cache size may result in lower memory usage at the cost of slower rendering. The default is false.

pub fn force_half_tone(self, do_set_flag: bool) -> Self

Controls whether Pdfium should always use halftone for image stretching. Halftone image stretching is often higher quality than linear image stretching but is much slower. The default is false.

pub fn use_print_quality(self, do_set_flag: bool) -> Self

Controls whether Pdfium should render for printing. The default is false.

Certain PDF files may stipulate different quality settings for on-screen display compared to printing. For these files, changing this setting to true will result in a higher quality rendered bitmap but slower performance. For PDF files that do not stipulate different quality settings, changing this setting will have no effect.

pub fn set_text_smoothing(self, do_set_flag: bool) -> Self

Controls whether rendered text should be anti-aliased. The default is true. The enabling of LCD-optimized text rendering via a call to PdfiumBitmapConfig::use_lcd_text_rendering(true) has no effect if this flag is set to false.

pub fn set_image_smoothing(self, do_set_flag: bool) -> Self

Controls whether rendered images should be anti-aliased. The default is true.

pub fn set_path_smoothing(self, do_set_flag: bool) -> Self

Controls whether rendered vector paths should be anti-aliased. The default is true.

pub fn set_reverse_byte_order(self, do_set_flag: bool) -> Self

Controls whether the byte order of generated image data should be reversed during rendering. The default is true, so that Pdfium returns pixel data as RGB8 rather than its default BGR8. There should generally be no need to change this flag, unless you want to do raw image processing and specifically need the pixel data returned by the PdfBitmap::as_bytes() function to be in BGR8 format.

pub fn render_fills_as_strokes(self, do_set_flag: bool) -> Self

Controls whether rendered vector fill paths need to be stroked. The default is false.

pub fn highlight_all_form_fields(self, color: PdfColor) -> Self

Highlights all rendered form fields with the given color. Note that specifying a solid color with no opacity will overprint any user data in the field.

pub fn highlight_button_form_fields(self, color: PdfColor) -> Self

Highlights all rendered push button form fields with the given color. Note that specifying a solid color with no opacity will overprint any user data in the field.

pub fn highlight_checkbox_form_fields(self, color: PdfColor) -> Self

Highlights all rendered checkbox form fields with the given color. Note that specifying a solid color with no opacity will overprint any user data in the field.

pub fn highlight_radio_button_form_fields(self, color: PdfColor) -> Self

Highlights all rendered radio button form fields with the given color. Note that specifying a solid color with no opacity will overprint any user data in the field.

pub fn highlight_combobox_form_fields(self, color: PdfColor) -> Self

Highlights all rendered combobox form fields with the given color. Note that specifying a solid color with no opacity will overprint any user data in the field.

pub fn highlight_listbox_form_fields(self, color: PdfColor) -> Self

Highlights all rendered listbox form fields with the given color. Note that specifying a solid color with no opacity will overprint any user data in the field.

pub fn highlight_text_form_fields(self, color: PdfColor) -> Self

Highlights all rendered text entry form fields with the given color. Note that specifying a solid color with no opacity will overprint any user data in the field.

pub fn highlight_signature_form_fields(self, color: PdfColor) -> Self

Highlights all rendered signature form fields with the given color. Note that specifying a solid color with no opacity will overprint any user data in the field.

pub fn highlight_form_fields_of_type(
    self,
    form_field_type: PdfFormFieldType,
    color: PdfColor
) -> Self

Highlights all rendered form fields matching the given type with the given color. Note that specifying a solid color with no opacity will overprint any user data in the field.

pub fn transform(
    self,
    a: f32,
    b: f32,
    c: f32,
    d: f32,
    e: f32,
    f: f32
) -> Result<Self, PdfiumError>

Applies the given transformation, expressed as six values representing the six configurable elements of a nine-element 3x3 PDF transformation matrix, to a PdfPage during rendering.

The transformation will be rejected with an error if applying it would result in a transformation matrix with a determinant of zero. Pdfium’s page rendering behaviour is undefined if the transformation matrix has a determinant of zero.

Pdfium’s rendering pipeline supports either rendering with form data or rendering with a custom transformation matrix, but not both at the same time. Applying any transformation automatically disables rendering of form data. If you must render form data while simultaneously applying transformations, consider using the PdfPage::flatten() function to flatten the form elements and form data into the containing page.

To move, scale, rotate, or skew a PdfPage during rendering, consider using one or more of the following functions. Internally they all use PdfRenderConfig::transform(), but are probably easier to use (and certainly clearer in their intent) in most situations.

• PdfRenderConfig::translate(): changes the origin of the rendered PdfPage.
• PdfRenderConfig::scale(): changes the size of the rendered PdfPage.
• PdfRenderConfig::rotate_clockwise_degrees(), PdfRenderConfig::rotate_counter_clockwise_degrees(), PdfRenderConfig::rotate_clockwise_radians(), PdfRenderConfig::rotate_counter_clockwise_radians(): rotates the rendered PdfPage around the origin.
• PdfRenderConfig::skew_degrees(), PdfRenderConfig::skew_radians(): skews the rendered PdfPage relative to its axes.

The order in which transformations are applied is significant. For example, the result of rotating then translating a page during rendering may be vastly different from translating then rotating the same page. In general, to obtain the expected results, transformations should be performed in the following order:

• Scale and/or skew
• Rotate
• Translate

An overview of PDF transformation matrices can be found in the PDF Reference Manual version 1.7 on page 204; a detailed description can be founded in section 4.2.3 on page 207.

pub fn translate(
    self,
    delta_x: PdfPoints,
    delta_y: PdfPoints
) -> Result<Self, PdfiumError>

Moves the origin of a PdfPage by the given horizontal and vertical distances during rendering.

Pdfium’s rendering pipeline supports either rendering with form data or rendering with a custom transformation matrix, but not both at the same time. Applying any transformation automatically disables rendering of form data. If you must render form data while simultaneously applying transformations, consider using the PdfPage::flatten() function to flatten the form elements and form data into the containing page.

pub fn scale(
    self,
    horizontal_scale_factor: f32,
    vertical_scale_factor: f32
) -> Result<Self, PdfiumError>

Changes the size of a PdfPage during rendering, scaling it by the given horizontal and vertical scale factors.

Pdfium’s rendering pipeline supports either rendering with form data or rendering with a custom transformation matrix, but not both at the same time. Applying any transformation automatically disables rendering of form data. If you must render form data while simultaneously applying transformations, consider using the PdfPage::flatten() function to flatten the form elements and form data into the containing page.

pub fn flip_horizontally(self) -> Result<Self, PdfiumError>

Flips a PdfPage horizontally around the origin during rendering by applying a horizontal scale factor of -1.

Pdfium’s rendering pipeline supports either rendering with form data or rendering with a custom transformation matrix, but not both at the same time. Applying any transformation automatically disables rendering of form data. If you must render form data while simultaneously applying transformations, consider using the PdfPage::flatten() function to flatten the form elements and form data into the containing page.

pub fn flip_vertically(self) -> Result<Self, PdfiumError>

Flips a PdfPage vertically around the origin during rendering by applying a vertical scale factor of -1.

Pdfium’s rendering pipeline supports either rendering with form data or rendering with a custom transformation matrix, but not both at the same time. Applying any transformation automatically disables rendering of form data. If you must render form data while simultaneously applying transformations, consider using the PdfPage::flatten() function to flatten the form elements and form data into the containing page.

pub fn reflect(self) -> Result<Self, PdfiumError>

Reflects a PdfPage by flipping it both horizontally and vertically around the origin during rendering.

Pdfium’s rendering pipeline supports either rendering with form data or rendering with a custom transformation matrix, but not both at the same time. Applying any transformation automatically disables rendering of form data. If you must render form data while simultaneously applying transformations, consider using the PdfPage::flatten() function to flatten the form elements and form data into the containing page.

pub fn rotate_counter_clockwise_degrees(
    self,
    degrees: f32
) -> Result<Self, PdfiumError>

Rotates a PdfPage counter-clockwise during rendering by the given number of degrees.

Any constraints on the final pixel width or height of the rendered image, set by a call to PdfRenderConfig::set_maximum_width() or PdfRenderConfig::set_maximum_height(), are not rotated. To rotate a page by a 90-degree increment while also rotating any constraints on the final pixel width and height of the rendered image, use one of the PdfRenderConfig::rotate(), PdfRenderConfig::rotate_if_portrait(), or PdfRenderConfig::rotate_if_landscape() functions.

Pdfium’s rendering pipeline supports either rendering with form data or rendering with a custom transformation matrix, but not both at the same time. Applying any transformation automatically disables rendering of form data. If you must render form data while simultaneously applying transformations, consider using the PdfPage::flatten() function to flatten the form elements and form data into the containing page.

pub fn rotate_clockwise_degrees(self, degrees: f32) -> Result<Self, PdfiumError>

Rotates a PdfPage clockwise during rendering by the given number of degrees.

Any constraints on the final pixel width or height of the rendered image, set by a call to PdfRenderConfig::set_maximum_width() or PdfRenderConfig::set_maximum_height(), are not rotated. To rotate a page by a 90-degree increment while also rotating any constraints on the final pixel width and height of the rendered image, use one of the PdfRenderConfig::rotate(), PdfRenderConfig::rotate_if_portrait(), or PdfRenderConfig::rotate_if_landscape() functions.

Pdfium’s rendering pipeline supports either rendering with form data or rendering with a custom transformation matrix, but not both at the same time. Applying any transformation automatically disables rendering of form data. If you must render form data while simultaneously applying transformations, consider using the PdfPage::flatten() function to flatten the form elements and form data into the containing page.

pub fn rotate_counter_clockwise_radians(
    self,
    radians: f32
) -> Result<Self, PdfiumError>

Rotates a PdfPage counter-clockwise during rendering by the given number of radians.

Any constraints on the final pixel width or height of the rendered image, set by a call to PdfRenderConfig::set_maximum_width() or PdfRenderConfig::set_maximum_height(), are not rotated. To rotate a page by a 90-degree increment while also rotating any constraints on the final pixel width and height of the rendered image, use one of the PdfRenderConfig::rotate(), PdfRenderConfig::rotate_if_portrait(), or PdfRenderConfig::rotate_if_landscape() functions.

Pdfium’s rendering pipeline supports either rendering with form data or rendering with a custom transformation matrix, but not both at the same time. Applying any transformation automatically disables rendering of form data. If you must render form data while simultaneously applying transformations, consider using the PdfPage::flatten() function to flatten the form elements and form data into the containing page.

pub fn rotate_clockwise_radians(self, radians: f32) -> Result<Self, PdfiumError>

Rotates a PdfPage clockwise during rendering by the given number of radians.

Any constraints on the final pixel width or height of the rendered image, set by a call to PdfRenderConfig::set_maximum_width() or PdfRenderConfig::set_maximum_height(), are not rotated. To rotate a page by a 90-degree increment while also rotating any constraints on the final pixel width and height of the rendered image, use one of the PdfRenderConfig::rotate(), PdfRenderConfig::rotate_if_portrait(), or PdfRenderConfig::rotate_if_landscape() functions.

Pdfium’s rendering pipeline supports either rendering with form data or rendering with a custom transformation matrix, but not both at the same time. Applying any transformation automatically disables rendering of form data. If you must render form data while simultaneously applying transformations, consider using the PdfPage::flatten() function to flatten the form elements and form data into the containing page.

pub fn skew_degrees(
    self,
    x_axis_skew: f32,
    y_axis_skew: f32
) -> Result<Self, PdfiumError>

Skews the axes of a PdfPage during rendering by the given angles in degrees.

Pdfium’s rendering pipeline supports either rendering with form data or rendering with a custom transformation matrix, but not both at the same time. Applying any transformation automatically disables rendering of form data. If you must render form data while simultaneously applying transformations, consider using the PdfPage::flatten() function to flatten the form elements and form data into the containing page.

pub fn skew_radians(
    self,
    x_axis_skew: f32,
    y_axis_skew: f32
) -> Result<Self, PdfiumError>

Skews the axes of a PdfPage during rendering by the given angles in radians.

Pdfium’s rendering pipeline supports either rendering with form data or rendering with a custom transformation matrix, but not both at the same time. Applying any transformation automatically disables rendering of form data. If you must render form data while simultaneously applying transformations, consider using the PdfPage::flatten() function to flatten the form elements and form data into the containing page.

pub fn clip(self, left: Pixels, top: Pixels, right: Pixels, bottom: Pixels) -> Self

Clips rendering output to the given pixel coordinates.

Trait Implementations

impl Default for PdfRenderConfig

fn default() -> Self

Returns the “default value” for a type.