pdfium_render/pdf/document/page/

render_config.rs

//! Defines the [PdfRenderConfig] struct, a builder-based approach to configuring
//! the rendering of [PdfBitmap] objects from one or more [PdfPage] objects.

use crate::bindgen::{
    FPDF_ANNOT, FPDF_CONVERT_FILL_TO_STROKE, FPDF_DWORD, FPDF_GRAYSCALE, FPDF_LCD_TEXT,
    FPDF_NO_NATIVETEXT, FPDF_PRINTING, FPDF_RENDER_FORCEHALFTONE, FPDF_RENDER_LIMITEDIMAGECACHE,
    FPDF_RENDER_NO_SMOOTHIMAGE, FPDF_RENDER_NO_SMOOTHPATH, FPDF_RENDER_NO_SMOOTHTEXT,
    FPDF_REVERSE_BYTE_ORDER, FS_MATRIX, FS_RECTF,
};
use crate::create_transform_setters;
use crate::error::PdfiumError;
use crate::pdf::bitmap::{PdfBitmap, PdfBitmapFormat, Pixels};
use crate::pdf::color::PdfColor;
use crate::pdf::document::page::field::PdfFormFieldType;
use crate::pdf::document::page::PdfPageOrientation::{Landscape, Portrait};
use crate::pdf::document::page::{PdfPage, PdfPageOrientation, PdfPageRenderRotation};
use crate::pdf::matrix::{PdfMatrix, PdfMatrixValue};
use crate::pdf::points::PdfPoints;
use std::os::raw::c_int;

/// 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 pixel size
/// constraints to the scaled width and height of the final rendering, 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.
pub struct PdfRenderConfig {
    use_auto_scaling: bool,
    start_x: Pixels,
    start_y: Pixels,
    fixed_width: Option<Pixels>,
    fixed_height: Option<Pixels>,
    target_width: Option<Pixels>,
    target_height: Option<Pixels>,
    scale_width_factor: Option<f32>,
    scale_height_factor: Option<f32>,
    maximum_width: Option<Pixels>,
    maximum_height: Option<Pixels>,
    portrait_rotation: PdfPageRenderRotation,
    portrait_rotation_do_rotate_constraints: bool,
    landscape_rotation: PdfPageRenderRotation,
    landscape_rotation_do_rotate_constraints: bool,
    format: PdfBitmapFormat,
    do_clear_bitmap_before_rendering: bool,
    clear_color: PdfColor,
    do_render_form_data: bool,
    form_field_highlight: Option<Vec<(PdfFormFieldType, PdfColor)>>,
    transformation_matrix: PdfMatrix,
    clip_rect: Option<(Pixels, Pixels, Pixels, Pixels)>,

    // The fields below set Pdfium's page rendering flags. Coverage for the
    // FPDF_DEBUG_INFO and FPDF_NO_CATCH flags is omitted since they are obsolete.
    do_set_flag_render_annotations: bool,     // Sets FPDF_ANNOT
    do_set_flag_use_lcd_text_rendering: bool, // Sets FPDF_LCD_TEXT
    do_set_flag_no_native_text: bool,         // Sets FPDF_NO_NATIVETEXT
    do_set_flag_grayscale: bool,              // Sets FPDF_GRAYSCALE
    do_set_flag_render_limited_image_cache: bool, // Sets FPDF_RENDER_LIMITEDIMAGECACHE
    do_set_flag_render_force_half_tone: bool, // Sets FPDF_RENDER_FORCEHALFTONE
    do_set_flag_render_for_printing: bool,    // Sets FPDF_PRINTING
    do_set_flag_render_no_smooth_text: bool,  // Sets FPDF_RENDER_NO_SMOOTHTEXT
    do_set_flag_render_no_smooth_image: bool, // Sets FPDF_RENDER_NO_SMOOTHIMAGE
    do_set_flag_render_no_smooth_path: bool,  // Sets FPDF_RENDER_NO_SMOOTHPATH
    do_set_flag_reverse_byte_order: bool,     // Sets FPDF_REVERSE_BYTE_ORDER
    do_set_flag_convert_fill_to_stroke: bool, // Sets FPDF_CONVERT_FILL_TO_STROKE
}

impl PdfRenderConfig {
    /// Creates a new [PdfRenderConfig] object with all settings initialized to their default values.
    pub fn new() -> Self {
        PdfRenderConfig {
            use_auto_scaling: true,
            start_x: 0,
            start_y: 0,
            fixed_width: None,
            fixed_height: None,
            target_width: None,
            target_height: None,
            scale_width_factor: None,
            scale_height_factor: None,
            maximum_width: None,
            maximum_height: None,
            portrait_rotation: PdfPageRenderRotation::None,
            portrait_rotation_do_rotate_constraints: false,
            landscape_rotation: PdfPageRenderRotation::None,
            landscape_rotation_do_rotate_constraints: false,
            format: PdfBitmapFormat::default(),
            do_clear_bitmap_before_rendering: true,
            clear_color: PdfColor::WHITE,
            do_render_form_data: true,
            form_field_highlight: None,
            transformation_matrix: PdfMatrix::IDENTITY,
            clip_rect: None,
            do_set_flag_render_annotations: true,
            do_set_flag_use_lcd_text_rendering: false,
            do_set_flag_no_native_text: false,
            do_set_flag_grayscale: false,
            do_set_flag_render_limited_image_cache: false,
            do_set_flag_render_force_half_tone: false,
            do_set_flag_render_for_printing: false,
            do_set_flag_render_no_smooth_text: false,
            do_set_flag_render_no_smooth_image: false,
            do_set_flag_render_no_smooth_path: false,
            do_set_flag_convert_fill_to_stroke: false,

            // We ask Pdfium to reverse its bitmap byte order from BGR8 to RGB8 in order
            // to make working with Image::DynamicImage easier after version 0.24. See:
            // https://github.com/ajrcarey/pdfium-render/issues/9
            do_set_flag_reverse_byte_order: true,
        }
    }

    /// 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.
    #[inline]
    pub fn thumbnail(self, size: Pixels) -> Self {
        self.set_target_size(size, size)
            .set_maximum_width(size)
            .set_maximum_height(size)
            .rotate(PdfPageRenderRotation::None, false)
            .use_print_quality(false)
            .set_image_smoothing(false)
            .render_annotations(false)
            .render_form_data(false)
    }

    /// Sets the desired pixel width and height of a rendered [PdfPage] to the
    /// width and height of the given [PdfBitmap]. No attempt will be made to scale or adjust
    /// the aspect ratio to match the source page. Overrides any previous call to
    /// [PdfRenderConfig::set_target_size], [PdfRenderConfig::set_target_width], or
    /// [PdfRenderConfig::set_target_height].
    #[inline]
    pub fn set_fixed_size_to_bitmap(self, bitmap: &PdfBitmap) -> Self {
        self.set_fixed_size(bitmap.width(), bitmap.height())
    }

    /// Sets the desired pixel width and height of a rendered [PdfPage] to the given
    /// pixel values. No attempt will be made to scale or adjust the aspect ratio to
    /// match the source page. Overrides any previous call to [PdfRenderConfig::set_target_size],
    /// [PdfRenderConfig::set_target_width], or [PdfRenderConfig::set_target_height].
    #[inline]
    pub fn set_fixed_size(self, width: Pixels, height: Pixels) -> Self {
        self.set_fixed_width(width).set_fixed_height(height)
    }

    /// Sets the desired pixel width of a rendered [PdfPage] to the given value. Overrides
    /// any previous call to [PdfRenderConfig::set_target_size] or [PdfRenderConfig::set_target_width].
    #[inline]
    pub fn set_fixed_width(mut self, width: Pixels) -> Self {
        self.use_auto_scaling = false;
        self.fixed_width = Some(width);

        self
    }

    /// Sets the desired pixel height of a rendered [PdfPage] to the given value. Overrides
    /// any previous call to [PdfRenderConfig::set_target_size] or [PdfRenderConfig::set_target_height].
    #[inline]
    pub fn set_fixed_height(mut self, height: Pixels) -> Self {
        self.use_auto_scaling = false;
        self.fixed_height = Some(height);

        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. Overrides any previous call to [PdfRenderConfig::set_fixed_width()]
    /// or [PdfRenderConfig::set_fixed_height()].
    #[inline]
    pub fn set_target_size(self, width: Pixels, height: Pixels) -> Self {
        self.set_target_width(width).set_target_height(height)
    }

    /// 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. Overrides any previous
    /// call to [PdfRenderConfig::set_fixed_width()] or [PdfRenderConfig::set_fixed_height()].
    #[inline]
    pub fn set_target_width(mut self, width: Pixels) -> Self {
        self.use_auto_scaling = true;
        self.target_width = Some(width);

        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. Overrides any previous
    /// call to [PdfRenderConfig::set_fixed_width()] or [PdfRenderConfig::set_fixed_height()].
    #[inline]
    pub fn set_target_height(mut self, height: Pixels) -> Self {
        self.use_auto_scaling = true;
        self.target_height = Some(height);

        self
    }

    /// Applies settings to this [PdfRenderConfig] suitable for filling the given [PdfBitmap].
    ///
    /// The source page's dimensions will be scaled so that both width and height attempt
    /// to fill, but do not exceed, the pixel dimensions of the bitmap. 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 bitmap width.
    #[inline]
    pub fn scale_page_to_bitmap(self, bitmap: &PdfBitmap) -> Self {
        self.scale_page_to_display_size(bitmap.width(), bitmap.height())
    }

    /// 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.
    #[inline]
    pub fn scale_page_to_display_size(mut self, width: Pixels, height: Pixels) -> Self {
        self.scale_width_factor = None;
        self.scale_height_factor = None;

        self.set_target_width(width)
            .set_maximum_width(width)
            .set_maximum_height(height)
            .rotate_if_landscape(PdfPageRenderRotation::Degrees90, true)
    }

    /// 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()].
    #[inline]
    pub fn scale_page_by_factor(self, scale: f32) -> Self {
        let result = self.scale_page_width_by_factor(scale);

        result.scale_page_height_by_factor(scale)
    }

    /// 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()].
    #[inline]
    pub fn scale_page_width_by_factor(mut self, scale: f32) -> Self {
        self.scale_width_factor = Some(scale);

        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()].
    #[inline]
    pub fn scale_page_height_by_factor(mut self, scale: f32) -> Self {
        self.scale_height_factor = Some(scale);

        self
    }

    /// Specifies that the final pixel width of the [PdfPage] will not exceed the given maximum.
    #[inline]
    pub fn set_maximum_width(mut self, width: Pixels) -> Self {
        self.maximum_width = Some(width);

        self
    }

    /// Specifies that the final pixel height of the [PdfPage] will not exceed the given maximum.
    #[inline]
    pub fn set_maximum_height(mut self, height: Pixels) -> Self {
        self.maximum_height = Some(height);

        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.
    #[inline]
    pub fn rotate(self, rotation: PdfPageRenderRotation, do_rotate_constraints: bool) -> Self {
        self.rotate_if_portrait(rotation, do_rotate_constraints)
            .rotate_if_landscape(rotation, do_rotate_constraints)
    }

    /// 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 [PdfPageRenderRotation::Degrees90] or [PdfPageRenderRotation::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.
    #[inline]
    pub fn rotate_if_portrait(
        mut self,
        rotation: PdfPageRenderRotation,
        do_rotate_constraints: bool,
    ) -> Self {
        self.portrait_rotation = rotation;

        if rotation == PdfPageRenderRotation::Degrees90
            || rotation == PdfPageRenderRotation::Degrees270
        {
            self.portrait_rotation_do_rotate_constraints = do_rotate_constraints;
        }

        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 [PdfPageRenderRotation::Degrees90] or [PdfPageRenderRotation::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.
    #[inline]
    pub fn rotate_if_landscape(
        mut self,
        rotation: PdfPageRenderRotation,
        do_rotate_constraints: bool,
    ) -> Self {
        self.landscape_rotation = rotation;

        if rotation == PdfPageRenderRotation::Degrees90
            || rotation == PdfPageRenderRotation::Degrees270
        {
            self.landscape_rotation_do_rotate_constraints = do_rotate_constraints;
        }

        self
    }

    /// Sets the pixel format that will be used during rendering of the [PdfPage].
    /// The default is [PdfBitmapFormat::BGRA].
    #[inline]
    pub fn set_format(mut self, format: PdfBitmapFormat) -> Self {
        self.format = format;

        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()].
    #[inline]
    pub fn clear_before_rendering(mut self, do_clear: bool) -> Self {
        self.do_clear_bitmap_before_rendering = do_clear;

        self
    }

    /// Sets the color applied to every pixel in the destination bitmap when clearing the bitmap
    /// before rendering the [PdfPage]. The default is [PdfColor::WHITE]. This setting
    /// has no effect if [PdfRenderConfig::clear_before_rendering()] is set to `false`.
    #[inline]
    pub fn set_clear_color(mut self, color: PdfColor) -> Self {
        self.clear_color = color;

        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.
    #[inline]
    pub fn render_form_data(mut self, do_render: bool) -> Self {
        self.do_render_form_data = do_render;

        self
    }

    /// Controls whether user-supplied annotations should be included during rendering of
    /// the [PdfPage]. The default is `true`.
    #[inline]
    pub fn render_annotations(mut self, do_render: bool) -> Self {
        self.do_set_flag_render_annotations = do_render;

        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)`.
    #[inline]
    pub fn use_lcd_text_rendering(mut self, do_set_flag: bool) -> Self {
        self.do_set_flag_use_lcd_text_rendering = do_set_flag;

        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`.
    #[inline]
    pub fn disable_native_text_rendering(mut self, do_set_flag: bool) -> Self {
        self.do_set_flag_no_native_text = do_set_flag;

        self
    }

    /// Controls whether rendering output should be grayscale rather than full color.
    /// The default is `false`.
    #[inline]
    pub fn use_grayscale_rendering(mut self, do_set_flag: bool) -> Self {
        self.do_set_flag_grayscale = do_set_flag;

        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`.
    #[inline]
    pub fn limit_render_image_cache_size(mut self, do_set_flag: bool) -> Self {
        self.do_set_flag_render_limited_image_cache = do_set_flag;

        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`.
    #[inline]
    pub fn force_half_tone(mut self, do_set_flag: bool) -> Self {
        self.do_set_flag_render_force_half_tone = do_set_flag;

        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.
    #[inline]
    pub fn use_print_quality(mut self, do_set_flag: bool) -> Self {
        self.do_set_flag_render_for_printing = do_set_flag;

        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`.
    #[inline]
    pub fn set_text_smoothing(mut self, do_set_flag: bool) -> Self {
        self.do_set_flag_render_no_smooth_text = !do_set_flag;

        self
    }

    /// Controls whether rendered images should be anti-aliased.
    /// The default is `true`.
    #[inline]
    pub fn set_image_smoothing(mut self, do_set_flag: bool) -> Self {
        self.do_set_flag_render_no_smooth_image = !do_set_flag;

        self
    }

    /// Controls whether rendered vector paths should be anti-aliased.
    /// The default is `true`.
    #[inline]
    pub fn set_path_smoothing(mut self, do_set_flag: bool) -> Self {
        self.do_set_flag_render_no_smooth_path = !do_set_flag;

        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
    /// four-channel RGBA rather than its default of four-channel BGRA.
    ///
    /// 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_raw_bytes()] function to be in BGR8 format.
    #[inline]
    pub fn set_reverse_byte_order(mut self, do_set_flag: bool) -> Self {
        self.do_set_flag_reverse_byte_order = do_set_flag;

        self
    }

    /// Controls whether rendered vector fill paths need to be stroked.
    /// The default is `false`.
    #[inline]
    pub fn render_fills_as_strokes(mut self, do_set_flag: bool) -> Self {
        self.do_set_flag_convert_fill_to_stroke = do_set_flag;

        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.
    #[inline]
    pub fn highlight_all_form_fields(self, color: PdfColor) -> Self {
        self.highlight_form_fields_of_type(PdfFormFieldType::Unknown, color)
    }

    /// 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.
    #[inline]
    pub fn highlight_button_form_fields(self, color: PdfColor) -> Self {
        self.highlight_form_fields_of_type(PdfFormFieldType::PushButton, color)
    }

    /// 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.
    #[inline]
    pub fn highlight_checkbox_form_fields(self, color: PdfColor) -> Self {
        self.highlight_form_fields_of_type(PdfFormFieldType::Checkbox, color)
    }

    /// 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.
    #[inline]
    pub fn highlight_radio_button_form_fields(self, color: PdfColor) -> Self {
        self.highlight_form_fields_of_type(PdfFormFieldType::RadioButton, color)
    }

    /// 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.
    #[inline]
    pub fn highlight_combobox_form_fields(self, color: PdfColor) -> Self {
        self.highlight_form_fields_of_type(PdfFormFieldType::ComboBox, color)
    }

    /// 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.
    #[inline]
    pub fn highlight_listbox_form_fields(self, color: PdfColor) -> Self {
        self.highlight_form_fields_of_type(PdfFormFieldType::ListBox, color)
    }

    /// 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.
    #[inline]
    pub fn highlight_text_form_fields(self, color: PdfColor) -> Self {
        self.highlight_form_fields_of_type(PdfFormFieldType::Text, color)
    }

    /// 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.
    #[inline]
    pub fn highlight_signature_form_fields(self, color: PdfColor) -> Self {
        self.highlight_form_fields_of_type(PdfFormFieldType::Signature, color)
    }

    /// 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.
    #[inline]
    pub fn highlight_form_fields_of_type(
        mut self,
        form_field_type: PdfFormFieldType,
        color: PdfColor,
    ) -> Self {
        if let Some(form_field_highlight) = self.form_field_highlight.as_mut() {
            form_field_highlight.push((form_field_type, color));
        } else {
            self.form_field_highlight = Some(vec![(form_field_type, color)]);
        }

        self
    }

    create_transform_setters!(
        Self,
        Result<Self, PdfiumError>,
        "the [PdfPage] during rendering",
        "the [PdfPage] during rendering.",
        "the [PdfPage] 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 a transformation via
        these setters 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. Note that matrix-based
        transformations will be applied _in addition to_ any intrinsic page rotation previously set
        using the [PdfRenderConfig::rotate()], [PdfRenderConfig::rotate_if_portrait()], or
        [PdfRenderConfig::rotate_if_landscape()] functions."
    );

    // The internal implementation of the transform() function used by the create_transform_setters!() macro.
    fn transform_impl(
        mut self,
        a: PdfMatrixValue,
        b: PdfMatrixValue,
        c: PdfMatrixValue,
        d: PdfMatrixValue,
        e: PdfMatrixValue,
        f: PdfMatrixValue,
    ) -> Result<Self, PdfiumError> {
        let result = self
            .transformation_matrix
            .multiply(PdfMatrix::new(a, b, c, d, e, f));

        if result.determinant() == 0.0 {
            Err(PdfiumError::InvalidTransformationMatrix)
        } else {
            self.transformation_matrix = result;
            self.do_render_form_data = false;

            Ok(self)
        }
    }

    // The internal implementation of the reset_matrix() function used by the create_transform_setters!() macro.
    fn reset_matrix_impl(mut self, matrix: PdfMatrix) -> Result<Self, PdfiumError> {
        self.transformation_matrix = matrix;

        Ok(self)
    }

    /// Clips rendering output to the given pixel coordinates. Pdfium will not render outside
    /// the clipping area; any existing image data in the destination [PdfBitmap] will remain
    /// intact.
    ///
    /// Pdfium's rendering pipeline supports _either_ rendering with form data _or_ clipping rendering
    /// output, but not both at the same time. Applying a clipping rectangle automatically disables
    /// rendering of form data. If you must render form data while simultaneously applying a
    /// clipping rectangle, consider using the [PdfPage::flatten()] function to flatten the
    /// form elements and form data into the containing page.
    #[inline]
    pub fn clip(mut self, left: Pixels, top: Pixels, right: Pixels, bottom: Pixels) -> Self {
        self.clip_rect = Some((left, top, right, bottom));
        self.do_render_form_data = false;

        self
    }

    /// Sets the position of the page's top-left corner within the destination [PdfBitmap],
    /// in bitmap pixel coordinates.
    ///
    /// The default is `(0, 0)`, which renders the page's top-left corner at the bitmap's
    /// top-left corner. Negative offsets push the page off the bitmap's top-left edge;
    /// positive offsets push it down and right. The rendered page is clipped to the
    /// destination bitmap's own width and height, so a strip-sized destination bitmap
    /// combined with a negative `y` offset can be used to render a horizontal strip from
    /// a large page without having to render the page in its entirety.
    ///
    /// To render rows `[y_offset, y_offset + strip_height)` of a page into a strip-sized
    /// destination bitmap, call `set_origin(0, -y_offset)` and pass a destination bitmap
    /// with a height of `strip_height`.
    ///
    /// Pdfium's rendering pipeline _either_ rendering with form data _or_ rendering with
    /// a custom transformation matrix, but not both at the same time. Since `set_origin()`
    /// affects rendering with form data, it is disabled automatically on applying any
    /// transformation.
    #[inline]
    pub fn set_origin(mut self, left: Pixels, top: Pixels) -> Self {
        self.start_x = left;
        self.start_y = top;

        self
    }

    /// Computes the pixel dimensions and rotation settings for the given [PdfPage]
    /// based on the configuration of this [PdfRenderConfig].
    #[inline]
    pub(crate) fn apply_to_page(&self, page: &PdfPage) -> PdfPageRenderSettings {
        let source_width = page.width();

        let source_height = page.height();

        let source_orientation =
            PdfPageOrientation::from_width_and_height(source_width, source_height);

        // Do we need to apply any rotation?

        let (target_rotation, do_rotate_constraints) = if source_orientation == Portrait
            && self.portrait_rotation != PdfPageRenderRotation::None
        {
            (
                self.portrait_rotation,
                self.portrait_rotation_do_rotate_constraints,
            )
        } else if source_orientation == Landscape
            && self.landscape_rotation != PdfPageRenderRotation::None
        {
            (
                self.landscape_rotation,
                self.landscape_rotation_do_rotate_constraints,
            )
        } else {
            (PdfPageRenderRotation::None, false)
        };

        let (output_width, output_height, width_scale, height_scale) = if self.use_auto_scaling {
            // Compute output width and height based on target sizes and page dimensions.

            let width_scale = if let Some(scale) = self.scale_width_factor {
                Some(scale)
            } else {
                self.target_width
                    .map(|target| (target as f32) / source_width.value)
            };

            let height_scale = if let Some(scale) = self.scale_height_factor {
                Some(scale)
            } else {
                self.target_height
                    .map(|target| (target as f32) / source_height.value)
            };

            // Maintain source aspect ratio if only one dimension's scale is set.

            let (do_maintain_aspect_ratio, mut width_scale, mut height_scale) =
                match (width_scale, height_scale) {
                    (Some(width_scale), Some(height_scale)) => {
                        (width_scale == height_scale, width_scale, height_scale)
                    }
                    (Some(width_scale), None) => (true, width_scale, width_scale),
                    (None, Some(height_scale)) => (true, height_scale, height_scale),
                    (None, None) => {
                        // Set default scale to 1.0 if neither dimension is specified.

                        (false, 1.0, 1.0)
                    }
                };

            // Apply constraints on maximum width and height, if any.

            let (source_width, source_height, width_constraint, height_constraint) =
                if do_rotate_constraints {
                    (
                        source_height,
                        source_width,
                        self.maximum_height,
                        self.maximum_width,
                    )
                } else {
                    (
                        source_width,
                        source_height,
                        self.maximum_width,
                        self.maximum_height,
                    )
                };

            if let Some(maximum) = width_constraint {
                let maximum = maximum as f32;

                if source_width.value * width_scale > maximum {
                    // Constrain the width, so it does not exceed the maximum.

                    width_scale = maximum / source_width.value;

                    if do_maintain_aspect_ratio {
                        height_scale = width_scale;
                    }
                }
            }

            if let Some(maximum) = height_constraint {
                let maximum = maximum as f32;

                if source_height.value * height_scale > maximum {
                    // Constrain the height, so it does not exceed the maximum.

                    height_scale = maximum / source_height.value;

                    if do_maintain_aspect_ratio {
                        width_scale = height_scale;
                    }
                }
            }

            (
                (source_width.value * width_scale).round() as c_int,
                (source_height.value * height_scale).round() as c_int,
                width_scale,
                height_scale,
            )
        } else {
            // Take output width and height directly from user's fixed settings.

            (
                self.fixed_width.unwrap_or(0) as c_int,
                self.fixed_height.unwrap_or(0) as c_int,
                self.scale_width_factor.unwrap_or(1.0),
                self.scale_height_factor.unwrap_or(1.0),
            )
        };

        // Compose render flags.

        let mut render_flags = 0;

        if self.do_set_flag_render_annotations {
            render_flags |= FPDF_ANNOT;
        }

        if self.do_set_flag_use_lcd_text_rendering {
            render_flags |= FPDF_LCD_TEXT;
        }

        if self.do_set_flag_no_native_text {
            render_flags |= FPDF_NO_NATIVETEXT;
        }

        if self.do_set_flag_grayscale {
            render_flags |= FPDF_GRAYSCALE;
        }

        if self.do_set_flag_render_limited_image_cache {
            render_flags |= FPDF_RENDER_LIMITEDIMAGECACHE;
        }

        if self.do_set_flag_render_force_half_tone {
            render_flags |= FPDF_RENDER_FORCEHALFTONE;
        }

        if self.do_set_flag_render_for_printing {
            render_flags |= FPDF_PRINTING;
        }

        if self.do_set_flag_render_no_smooth_text {
            render_flags |= FPDF_RENDER_NO_SMOOTHTEXT;
        }

        if self.do_set_flag_render_no_smooth_image {
            render_flags |= FPDF_RENDER_NO_SMOOTHIMAGE;
        }

        if self.do_set_flag_render_no_smooth_path {
            render_flags |= FPDF_RENDER_NO_SMOOTHPATH;
        }

        if self.do_set_flag_reverse_byte_order {
            render_flags |= FPDF_REVERSE_BYTE_ORDER;
        }

        if self.do_set_flag_convert_fill_to_stroke {
            render_flags |= FPDF_CONVERT_FILL_TO_STROKE;
        }

        // Pages can be rendered either _with_ transformation matrices and clipping
        // but _without_ form data, or _with_ form data but _without_ transformation matrices
        // and clipping. We need to be prepared for either option. If rendering of form data
        // is disabled, then the scaled output width and height and any user-specified
        // 90-degree rotation need to be applied to the transformation matrix now.

        let transformation_matrix = if !self.do_render_form_data {
            let result = if target_rotation != PdfPageRenderRotation::None {
                // Translate the origin to the center of the page before rotating.

                let (delta_x, delta_y) = match target_rotation {
                    PdfPageRenderRotation::None => unreachable!(),
                    PdfPageRenderRotation::Degrees90 => (PdfPoints::ZERO, -source_width),
                    PdfPageRenderRotation::Degrees180 => (-source_width, -source_height),
                    PdfPageRenderRotation::Degrees270 => (-source_height, PdfPoints::ZERO),
                };

                self.transformation_matrix
                    .translate(delta_x, delta_y)
                    .and_then(|result| {
                        result.rotate_clockwise_degrees(target_rotation.as_degrees())
                    })
            } else {
                Ok(self.transformation_matrix)
            };

            result.and_then(|result| result.scale(width_scale, height_scale))
        } else {
            Ok(PdfMatrix::identity())
        };

        PdfPageRenderSettings {
            start_x: self.start_x as c_int,
            start_y: self.start_y as c_int,
            width: output_width,
            height: output_height,
            format: self.format.as_pdfium() as c_int,
            rotate: target_rotation.as_pdfium(),
            do_clear_bitmap_before_rendering: self.do_clear_bitmap_before_rendering,
            clear_color: self.clear_color.as_pdfium_color(),
            do_render_form_data: self.do_render_form_data,
            form_field_highlight: if !self.do_render_form_data
                || self.form_field_highlight.is_none()
            {
                None
            } else {
                Some(
                    self.form_field_highlight
                        .as_ref()
                        .unwrap()
                        .iter()
                        .map(|(form_field_type, color)| {
                            (
                                form_field_type.as_pdfium() as c_int,
                                color.as_pdfium_color_with_alpha(),
                            )
                        })
                        .collect::<Vec<_>>(),
                )
            },
            matrix: transformation_matrix
                .unwrap_or(PdfMatrix::IDENTITY)
                .as_pdfium(),
            clipping: if let Some((left, top, right, bottom)) = self.clip_rect {
                FS_RECTF {
                    left: left as f32,
                    top: top as f32,
                    right: right as f32,
                    bottom: bottom as f32,
                }
            } else {
                FS_RECTF {
                    left: 0.0,
                    top: 0.0,
                    right: output_width as f32,
                    bottom: output_height as f32,
                }
            },
            render_flags: render_flags as c_int,
            is_reversed_byte_order_flag_set: self.do_set_flag_reverse_byte_order,
        }
    }
}

impl Default for PdfRenderConfig {
    #[inline]
    fn default() -> Self {
        PdfRenderConfig::new()
    }
}

/// Finalized rendering settings, ready to be passed to a Pdfium rendering function.
/// Generated by calling [PdfRenderConfig::apply_to_page()].
#[derive(Debug, Clone)]
pub(crate) struct PdfPageRenderSettings {
    pub(crate) start_x: c_int,
    pub(crate) start_y: c_int,
    pub(crate) width: c_int,
    pub(crate) height: c_int,
    pub(crate) format: c_int,
    pub(crate) rotate: c_int,
    pub(crate) do_clear_bitmap_before_rendering: bool,
    pub(crate) clear_color: FPDF_DWORD,
    pub(crate) do_render_form_data: bool,
    pub(crate) form_field_highlight: Option<Vec<(c_int, (FPDF_DWORD, u8))>>,
    pub(crate) matrix: FS_MATRIX,
    pub(crate) clipping: FS_RECTF,
    pub(crate) render_flags: c_int,
    pub(crate) is_reversed_byte_order_flag_set: bool,
}

#[cfg(test)]
mod tests {
    use crate::prelude::*;
    use crate::utils::test::test_bind_to_pdfium; // Temporary until PdfParagraph is included in the prelude.

    #[test]
    fn test_set_origin_default_settings_zero() -> Result<(), PdfiumError> {
        let render_settings = get_render_settings_from_config(PdfRenderConfig::new())?;

        assert_eq!(render_settings.start_x, 0);
        assert_eq!(render_settings.start_y, 0);

        Ok(())
    }

    #[test]
    fn test_set_origin_negative_offsets_pass_through() -> Result<(), PdfiumError> {
        let render_settings =
            get_render_settings_from_config(PdfRenderConfig::new().set_origin(-50, -400))?;

        assert_eq!(render_settings.start_x, -50);
        assert_eq!(render_settings.start_y, -400);

        Ok(())
    }

    #[test]
    fn test_set_origin_positive_offsets_pass_through() -> Result<(), PdfiumError> {
        let render_settings =
            get_render_settings_from_config(PdfRenderConfig::new().set_origin(75, 125))?;

        assert_eq!(render_settings.start_x, 75);
        assert_eq!(render_settings.start_y, 125);

        Ok(())
    }

    #[test]
    fn test_set_origin_strips_stitch_to_full_page() -> Result<(), PdfiumError> {
        // Compare a full page render of a sample page against a render assembled
        // from multiple stripped renders. The results should be identical.

        let pdfium = test_bind_to_pdfium();

        let document = pdfium.load_pdf_from_file("./test/image-test.pdf", None)?;
        let page = document.pages().first()?;

        // `image-test.pdf` is single-page A4: 595 × 842 points at 72 DPI outputs to
        // 595 × 842 pixels when rendered with `set_target_size(595, 842)`.

        let target_width: Pixels = 1000;
        let target_height: Pixels = 800;
        let strips: i32 = 4; // The number of render passes, with each pass outputting a single strip
        let strip_height: Pixels = target_height / strips as Pixels;

        assert_eq!(strip_height * strips, target_height);

        // First, create a full page render of the target page.

        let full_bitmap = page.render_with_config(
            &PdfRenderConfig::new().set_fixed_size(target_width, target_height),
        )?;
        let full_bytes = full_bitmap.as_image()?.to_rgba8().into_raw();
        let row_bytes = (target_width as usize) * 4;

        assert_eq!(full_bytes.len(), row_bytes * (target_height as usize));

        // Next, render the page in strips...

        let mut stitched: Vec<u8> = Vec::with_capacity(full_bytes.len());

        for i in 0..strips {
            let mut strip_bitmap =
                PdfBitmap::empty(target_width, strip_height, full_bitmap.format()?)?;

            page.render_into_bitmap_with_config(
                &mut strip_bitmap,
                &&PdfRenderConfig::new()
                    .set_fixed_size(target_width, target_height)
                    .set_origin(0, -(i * strip_height)),
            )?;

            // ... joining each strip in memory to build a complete rendered image.

            stitched.extend_from_slice(strip_bitmap.as_image()?.to_rgba8().as_raw());
        }

        // The render output assembled from the strips should exactly match the full page render.

        println!(
            "{}, {}, {}, {}",
            strip_height,
            strip_height * strips,
            target_height,
            row_bytes
        );
        assert_eq!(stitched.len(), full_bytes.len());

        let mut sums = [0u64; 4]; // Track per-channel mean drift between stitched and full-page renders.
        let pixel_count = full_bytes.len() / 4;

        for px in 0..pixel_count {
            for ch in 0..4 {
                let a = stitched[px * 4 + ch] as i32;
                let b = full_bytes[px * 4 + ch] as i32;
                sums[ch] += (a - b).unsigned_abs() as u64;
            }
        }

        let n = pixel_count as f64;
        let max_drift = (0..4).map(|ch| sums[ch] as f64 / n).fold(0.0_f64, f64::max);

        assert!(
            max_drift < 5.0,
            "stitched-vs-full per-channel mean drift {:.3}/255 exceeds tolerance",
            max_drift
        );

        Ok(())
    }

    #[test]
    fn test_fixed_size_render_config() -> Result<(), PdfiumError> {
        let render_settings =
            get_render_settings_from_config(PdfRenderConfig::new().set_fixed_size(2000, 2000))?;

        assert_eq!(render_settings.width, 2000);
        assert_eq!(render_settings.height, 2000);

        // Applying scaling does not affect the rendered bitmap size.

        let render_settings = get_render_settings_from_config(
            PdfRenderConfig::new()
                .set_fixed_size(2000, 2000)
                .scale_page_by_factor(5.0),
        )?;

        assert_eq!(render_settings.width, 2000);
        assert_eq!(render_settings.height, 2000);

        Ok(())
    }

    #[test]
    fn test_target_size_render_config() -> Result<(), PdfiumError> {
        let render_settings = get_render_settings_from_config(
            PdfRenderConfig::new().scale_page_to_display_size(2000, 2000),
        )?;

        assert_eq!(render_settings.width, 1414);
        assert_eq!(render_settings.height, 2000);

        // Applying scaling does affected the rendered bitmap size.

        let render_settings = get_render_settings_from_config(
            PdfRenderConfig::new()
                .set_target_size(2000, 2000)
                .scale_page_by_factor(5.0),
        )?;

        assert_eq!(render_settings.width, 2976);
        assert_eq!(render_settings.height, 4209);

        Ok(())
    }

    fn get_render_settings_from_config(
        config: PdfRenderConfig,
    ) -> Result<PdfPageRenderSettings, PdfiumError> {
        let pdfium = test_bind_to_pdfium();

        let mut document = pdfium.create_new_pdf()?;
        let page = document
            .pages_mut()
            .create_page_at_start(PdfPagePaperSize::Portrait(PdfPagePaperStandardSize::A4))?;

        Ok(config.apply_to_page(&page))
    }

    /// Per-pixel mean absolute difference across all RGBA channels. Returns
    /// infinity on a length mismatch so a dimension difference fails an
    /// equality check and passes a divergence check.
    fn mean_abs_diff(a: &[u8], b: &[u8]) -> f64 {
        if a.len() != b.len() {
            return f64::INFINITY;
        }

        let sum: u64 = a
            .iter()
            .zip(b)
            .map(|(x, y)| (*x as i64 - *y as i64).unsigned_abs())
            .sum();

        sum as f64 / a.len() as f64
    }

    /// Builds a single-page A4 document with two asymmetric filled rectangles,
    /// so that orientation is observable. A blank page would compare equal under
    /// any rotation, which is why content is required.
    fn create_asymmetric_a4(pdfium: &Pdfium) -> Result<PdfDocument<'_>, PdfiumError> {
        let mut document = pdfium.create_new_pdf()?;

        {
            let mut page = document
                .pages_mut()
                .create_page_at_start(PdfPagePaperSize::Portrait(PdfPagePaperStandardSize::A4))?;

            page.objects_mut().create_path_object_rect(
                PdfRect::new(
                    PdfPoints::new(640.0),
                    PdfPoints::new(60.0),
                    PdfPoints::new(800.0),
                    PdfPoints::new(300.0),
                ),
                None,
                None,
                Some(PdfColor::RED),
            )?;

            page.objects_mut().create_path_object_rect(
                PdfRect::new(
                    PdfPoints::new(40.0),
                    PdfPoints::new(400.0),
                    PdfPoints::new(120.0),
                    PdfPoints::new(560.0),
                ),
                None,
                None,
                Some(PdfColor::new(0, 0, 255, 255)),
            )?;
        }

        Ok(document)
    }

    /// `FPDF_RenderPageBitmapWithMatrix` composes the caller matrix on top of
    /// pdfium's display transform, which already applies the page's intrinsic
    /// `/Rotate`. So the matrix render path with an identity matrix must produce
    /// byte-identical output to the form-data path, which also applies `/Rotate`,
    /// for every `/Rotate` value. A caller that mistakenly believed the matrix
    /// path ignores `/Rotate` and pre-composed a rotation would fail this test.
    #[test]
    fn test_matrix_path_matches_form_path_for_each_intrinsic_rotation() -> Result<(), PdfiumError> {
        let pdfium = test_bind_to_pdfium();
        let mut document = create_asymmetric_a4(&pdfium)?;
        let mut page = document.pages_mut().first()?;

        for rotation in [
            PdfPageRenderRotation::None,
            PdfPageRenderRotation::Degrees90,
            PdfPageRenderRotation::Degrees180,
            PdfPageRenderRotation::Degrees270,
        ] {
            page.set_rotation(rotation);

            let width = page.width().value.round() as Pixels;
            let height = page.height().value.round() as Pixels;

            // Form-data path: applies `/Rotate` automatically.
            let form = page
                .render_with_config(&PdfRenderConfig::new().set_target_size(width, height))?
                .as_image()?
                .to_rgba8()
                .into_raw();

            // Matrix path with an identity matrix.
            let matrix = page
                .render_with_config(
                    &PdfRenderConfig::new()
                        .set_target_size(width, height)
                        .render_form_data(false),
                )?
                .as_image()?
                .to_rgba8()
                .into_raw();

            let drift = mean_abs_diff(&matrix, &form);
            assert!(
                drift < 1.0,
                "{rotation:?}: matrix path diverged from the form-data path ({drift:.3}/255), \
                 so the matrix path is not applying /Rotate the way this test assumes",
            );

            // Negative control: a half-scale matrix-path render must differ, so a
            // zero drift above can only mean genuine agreement, not two blanks.
            let control = page
                .render_with_config(
                    &PdfRenderConfig::new()
                        .set_fixed_size(width, height)
                        .render_form_data(false)
                        .scale_page_by_factor(0.5),
                )?
                .as_image()?
                .to_rgba8()
                .into_raw();

            assert!(
                mean_abs_diff(&control, &form) > 5.0,
                "{rotation:?}: negative control did not diverge, the comparison is not discriminating",
            );
        }

        Ok(())
    }

    /// Renders a `/Rotate 90` page as horizontal strips through the matrix path,
    /// using the device-space strip matrix `[s, 0, 0, s, 0, -y_offset]`, and
    /// stitches them. The result must match the full form-data render. If a
    /// caller baked a rotation into the strip matrix, the strips would not stitch
    /// to the correctly-rotated full render. `reset_matrix()` does not disable
    /// form data on its own, so `render_form_data(false)` is required.
    #[test]
    fn test_matrix_path_strip_stitch_matches_full_render() -> Result<(), PdfiumError> {
        let pdfium = test_bind_to_pdfium();
        let mut document = create_asymmetric_a4(&pdfium)?;
        let mut page = document.pages_mut().first()?;
        page.set_rotation(PdfPageRenderRotation::Degrees90);

        let width = page.width().value.round() as Pixels;
        let height = page.height().value.round() as Pixels;

        let full = page
            .render_with_config(&PdfRenderConfig::new().set_target_size(width, height))?
            .as_image()?
            .to_rgba8()
            .into_raw();

        let strips: Pixels = 5;
        let mut stitched: Vec<u8> = Vec::with_capacity(full.len());
        let mut y_offset: Pixels = 0;

        for i in 0..strips {
            // The last strip absorbs any remainder so the strips cover the page.
            let strip_height = if i == strips - 1 {
                height - y_offset
            } else {
                height / strips
            };

            let strip = page
                .render_with_config(
                    &PdfRenderConfig::new()
                        .set_fixed_size(width, strip_height)
                        .clip(0, 0, width, strip_height)
                        .render_form_data(false)
                        .reset_matrix(PdfMatrix::new(
                            1.0,
                            0.0,
                            0.0,
                            1.0,
                            0.0,
                            -(y_offset as f32),
                        ))?,
                )?
                .as_image()?
                .to_rgba8()
                .into_raw();

            stitched.extend_from_slice(&strip);
            y_offset += strip_height;
        }

        assert_eq!(
            stitched.len(),
            full.len(),
            "stitched strips must cover the full page",
        );

        let drift = mean_abs_diff(&stitched, &full);
        assert!(
            drift < 1.0,
            "matrix-path strips did not stitch to the full render ({drift:.3}/255)",
        );

        Ok(())
    }
}