rpdfium_render/

render_defines.rs

// Derived from PDFium's fpdfsdk/fpdf_view.cpp render configuration
// Original: Copyright 2014 The PDFium Authors
// Licensed under BSD-3-Clause / Apache-2.0
// See pdfium-upstream/LICENSE for the original license.

//! Render configuration for controlling output dimensions and background.

use std::sync::Arc;

use rpdfium_core::{Matrix, Rect};

use crate::color_convert::RgbaColor;

/// Callback for tile-based progressive rendering.
pub trait RenderProgress: Send + Sync {
    /// Called after each tile completes.
    /// Returns `true` to continue, `false` to cancel rendering.
    fn on_tile_complete(&self, tile_x: u32, tile_y: u32, total_tiles: u32) -> bool;
}

/// Forced color scheme for accessibility rendering (high-contrast mode).
/// Corresponds to CPDF_RenderOptions::ColorScheme.
///
/// Note: Upstream uses 4 forced colors (path_fill, path_stroke, text_fill, text_stroke).
/// rpdfium simplifies to 2 colors: text_color (all foreground elements) and
/// background_color. Stroke-specific coloring is intentionally unified with fill
/// coloring. This simplification covers all practical forced-color use cases.
#[derive(Debug, Clone, PartialEq)]
pub struct ColorScheme {
    /// Color used for all foreground (text, strokes, fills) content.
    pub text_color: RgbaColor,
    /// Color used for page backgrounds.
    pub background_color: RgbaColor,
}

impl ColorScheme {
    /// Standard high-contrast: black text on white background.
    pub fn high_contrast() -> Self {
        Self {
            text_color: RgbaColor {
                r: 0,
                g: 0,
                b: 0,
                a: 255,
            },
            background_color: RgbaColor {
                r: 255,
                g: 255,
                b: 255,
                a: 255,
            },
        }
    }
}

/// Configuration for rendering a page to a bitmap.
#[derive(Clone)]
pub struct RenderConfig {
    /// Output width in pixels.
    pub width: u32,
    /// Output height in pixels.
    pub height: u32,
    /// Background color.
    pub background: RgbaColor,
    /// Page media box in PDF user space units. When set, a page transform
    /// is computed to map PDF coordinates (bottom-left origin, Y up) to
    /// device coordinates (top-left origin, Y down), scaling to fit the
    /// requested `width` × `height`.
    ///
    /// When `None`, an identity transform is used — PDF coordinates map
    /// directly to pixel coordinates without Y-flip or scaling.
    pub media_box: Option<Rect>,
    /// Page rotation in degrees (0, 90, 180, or 270). Only used when
    /// `media_box` is `Some`.
    ///
    /// **Note:** For rotated pages (90° or 270°), the caller is responsible
    /// for swapping `width` and `height` to match the rotated dimensions.
    pub rotation: u32,
    /// Tile size in pixels for progressive rendering. `None` = render
    /// full page at once (default).
    pub tile_size: Option<u32>,
    /// Progress callback for tile-based rendering.
    pub progress: Option<Arc<dyn RenderProgress>>,
    /// Convert the output to grayscale after rendering. Default: `false`.
    pub grayscale: bool,
    /// Enable anti-aliasing for path rendering. Default: `true`.
    pub antialiasing: bool,
    /// Anti-aliasing for text rendering (default: `true`).
    /// When `false`, text glyph outlines are rendered without anti-aliasing.
    /// Corresponds to upstream `bNoTextSmooth` (inverted).
    pub text_antialiasing: bool,
    /// Anti-aliasing for path/vector rendering (default: `true`).
    /// When `false`, path fills and strokes are rendered without anti-aliasing.
    /// Corresponds to upstream `bNoPathSmooth` (inverted).
    pub path_antialiasing: bool,
    /// Anti-aliasing for image scaling (default: `true`).
    /// When `false`, images are rendered with nearest-neighbor interpolation.
    /// Corresponds to upstream `bNoImageSmooth` (inverted).
    pub image_antialiasing: bool,
    /// Custom page transform matrix.  When set, this overrides the matrix
    /// that would otherwise be computed from `media_box` and `rotation`.
    ///
    /// Corresponds to the `matrix` parameter of `FPDF_RenderPageBitmapWithMatrix`.
    pub custom_transform: Option<Matrix>,
    /// Device-space clip rectangle in pixel coordinates, where `(0, 0)` is the
    /// top-left corner of the bitmap, x increases rightward, and y increases
    /// downward.  The `Rect` fields map as: `left`/`right` for the x range and
    /// `bottom`/`top` for the y range (both inclusive-exclusive).  Pixels
    /// outside this rectangle are replaced by the `background` color after
    /// rendering.  `None` (default) means the full `width × height` surface is
    /// used.
    ///
    /// Corresponds to the `clipping` parameter of `FPDF_RenderPageBitmapWithMatrix`.
    pub clip_rect: Option<Rect>,
    /// If set, all fill/stroke colors are replaced with this scheme (accessibility mode).
    /// Corresponds to CPDF_RenderOptions::kForcedColor.
    pub forced_color_scheme: Option<ColorScheme>,
}

impl std::fmt::Debug for RenderConfig {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("RenderConfig")
            .field("width", &self.width)
            .field("height", &self.height)
            .field("background", &self.background)
            .field("media_box", &self.media_box)
            .field("rotation", &self.rotation)
            .field("tile_size", &self.tile_size)
            .field("progress", &self.progress.as_ref().map(|_| "..."))
            .field("grayscale", &self.grayscale)
            .field("antialiasing", &self.antialiasing)
            .field("text_antialiasing", &self.text_antialiasing)
            .field("path_antialiasing", &self.path_antialiasing)
            .field("image_antialiasing", &self.image_antialiasing)
            .field("custom_transform", &self.custom_transform)
            .field("clip_rect", &self.clip_rect)
            .field("forced_color_scheme", &self.forced_color_scheme)
            .finish()
    }
}

impl RenderConfig {
    /// Set the output dimensions in pixels.
    pub fn with_size(mut self, width: u32, height: u32) -> Self {
        self.width = width;
        self.height = height;
        self
    }

    /// Set the background color.
    pub fn with_background(mut self, bg: RgbaColor) -> Self {
        self.background = bg;
        self
    }

    /// Set the page media box for coordinate transformation.
    pub fn with_media_box(mut self, media_box: Rect) -> Self {
        self.media_box = Some(media_box);
        self
    }

    /// Set the page rotation in degrees (0, 90, 180, or 270).
    pub fn with_rotation(mut self, rotation: u32) -> Self {
        self.rotation = rotation;
        self
    }

    /// Set the tile size in pixels for progressive rendering.
    pub fn with_tile_size(mut self, size: u32) -> Self {
        self.tile_size = Some(size);
        self
    }

    /// Set the progress callback for tile-based rendering.
    pub fn with_progress(mut self, progress: Arc<dyn RenderProgress>) -> Self {
        self.progress = Some(progress);
        self
    }

    /// Enable or disable grayscale output conversion.
    pub fn with_grayscale(mut self, grayscale: bool) -> Self {
        self.grayscale = grayscale;
        self
    }

    /// Enable or disable anti-aliasing.
    pub fn with_antialiasing(mut self, antialiasing: bool) -> Self {
        self.antialiasing = antialiasing;
        self
    }

    /// Enable or disable anti-aliasing specifically for text rendering.
    pub fn with_text_antialiasing(mut self, aa: bool) -> Self {
        self.text_antialiasing = aa;
        self
    }

    /// Enable or disable anti-aliasing specifically for path/vector rendering.
    pub fn with_path_antialiasing(mut self, aa: bool) -> Self {
        self.path_antialiasing = aa;
        self
    }

    /// Enable or disable anti-aliasing specifically for image scaling.
    pub fn with_image_antialiasing(mut self, aa: bool) -> Self {
        self.image_antialiasing = aa;
        self
    }

    /// Set a custom page transform matrix, bypassing the `media_box`/`rotation`
    /// calculation.
    ///
    /// The matrix maps PDF user-space coordinates to device pixel coordinates.
    /// When set, `media_box` and `rotation` are ignored.
    ///
    /// Corresponds to `FPDF_RenderPageBitmapWithMatrix`.
    pub fn with_transform(mut self, matrix: Matrix) -> Self {
        self.custom_transform = Some(matrix);
        self
    }

    /// Set a device-space clip rectangle.
    ///
    /// Pixels outside `rect` are replaced with the `background` color after
    /// rendering.  Coordinates are in device pixels with the top-left corner
    /// at `(0, 0)`.
    ///
    /// Corresponds to the `clipping` parameter of `FPDF_RenderPageBitmapWithMatrix`.
    pub fn with_clip(mut self, rect: Rect) -> Self {
        self.clip_rect = Some(rect);
        self
    }

    /// Enable forced color mode for accessibility rendering.
    ///
    /// When set, all text, stroke, and fill colors are replaced with the
    /// specified colors.  Image content is not affected.
    ///
    /// Corresponds to `CPDF_RenderOptions::kForcedColor`.
    pub fn with_forced_colors(mut self, text: RgbaColor, background: RgbaColor) -> Self {
        self.forced_color_scheme = Some(ColorScheme {
            text_color: text,
            background_color: background,
        });
        self
    }
}

impl Default for RenderConfig {
    fn default() -> Self {
        Self {
            width: 612,
            height: 792,
            background: RgbaColor::WHITE,
            media_box: None,
            rotation: 0,
            tile_size: None,
            progress: None,
            grayscale: false,
            antialiasing: true,
            text_antialiasing: true,
            path_antialiasing: true,
            image_antialiasing: true,
            custom_transform: None,
            clip_rect: None,
            forced_color_scheme: None,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_default_config() {
        let config = RenderConfig::default();
        assert_eq!(config.width, 612);
        assert_eq!(config.height, 792);
        assert_eq!(config.background, RgbaColor::WHITE);
        assert!(config.media_box.is_none());
        assert_eq!(config.rotation, 0);
        assert!(config.tile_size.is_none());
        assert!(config.progress.is_none());
        assert!(!config.grayscale);
        assert!(config.antialiasing);
        assert!(config.text_antialiasing);
        assert!(config.path_antialiasing);
        assert!(config.image_antialiasing);
    }

    #[test]
    fn test_builder_with_size() {
        let config = RenderConfig::default().with_size(1024, 768);
        assert_eq!(config.width, 1024);
        assert_eq!(config.height, 768);
    }

    #[test]
    fn test_builder_with_background() {
        let bg = RgbaColor {
            r: 255,
            g: 0,
            b: 0,
            a: 255,
        };
        let config = RenderConfig::default().with_background(bg);
        assert_eq!(config.background.r, 255);
        assert_eq!(config.background.g, 0);
    }

    #[test]
    fn test_builder_with_media_box() {
        let rect = Rect::new(0.0, 0.0, 612.0, 792.0);
        let config = RenderConfig::default().with_media_box(rect);
        assert!(config.media_box.is_some());
        let mb = config.media_box.unwrap();
        assert_eq!(mb.right, 612.0);
        assert_eq!(mb.top, 792.0);
    }

    #[test]
    fn test_builder_with_rotation() {
        let config = RenderConfig::default().with_rotation(90);
        assert_eq!(config.rotation, 90);
    }

    #[test]
    fn test_builder_chaining() {
        let config = RenderConfig::default()
            .with_size(800, 600)
            .with_rotation(180)
            .with_background(RgbaColor {
                r: 0,
                g: 0,
                b: 0,
                a: 255,
            });
        assert_eq!(config.width, 800);
        assert_eq!(config.height, 600);
        assert_eq!(config.rotation, 180);
        assert_eq!(config.background.r, 0);
    }

    #[test]
    fn test_config_is_send_sync() {
        fn assert_send_sync<T: Send + Sync>() {}
        assert_send_sync::<RenderConfig>();
    }

    #[test]
    fn test_builder_with_tile_size() {
        let config = RenderConfig::default().with_tile_size(256);
        assert_eq!(config.tile_size, Some(256));
    }

    #[test]
    fn test_builder_with_progress() {
        struct TestProgress;
        impl RenderProgress for TestProgress {
            fn on_tile_complete(&self, _tx: u32, _ty: u32, _total: u32) -> bool {
                true
            }
        }
        let config = RenderConfig::default().with_progress(Arc::new(TestProgress));
        assert!(config.progress.is_some());
    }

    #[test]
    fn test_builder_with_grayscale() {
        let config = RenderConfig::default().with_grayscale(true);
        assert!(config.grayscale);
    }

    #[test]
    fn test_builder_with_antialiasing() {
        let config = RenderConfig::default().with_antialiasing(false);
        assert!(!config.antialiasing);
    }

    #[test]
    fn test_grayscale_conversion() {
        // Verify the grayscale formula: gray = (r*299 + g*587 + b*114) / 1000
        let r: u32 = 255;
        let g: u32 = 0;
        let b: u32 = 0;
        let gray = (r * 299 + g * 587 + b * 114) / 1000;
        assert_eq!(gray, 76); // Pure red → grayish

        let gray_white = (255 * 299 + 255 * 587 + 255 * 114) / 1000;
        assert_eq!(gray_white, 255);

        let gray_black = 0; // Black: (0 * 299 + 0 * 587 + 0 * 114) / 1000
        assert_eq!(gray_black, 0);
    }

    #[test]
    fn test_color_scheme_high_contrast() {
        let scheme = ColorScheme::high_contrast();
        assert_eq!(
            scheme.text_color,
            RgbaColor {
                r: 0,
                g: 0,
                b: 0,
                a: 255
            }
        );
        assert_eq!(
            scheme.background_color,
            RgbaColor {
                r: 255,
                g: 255,
                b: 255,
                a: 255
            }
        );
    }

    #[test]
    fn test_render_config_with_forced_colors_builder() {
        let text = RgbaColor {
            r: 255,
            g: 255,
            b: 0,
            a: 255,
        };
        let bg = RgbaColor {
            r: 0,
            g: 0,
            b: 128,
            a: 255,
        };
        let config = RenderConfig::default().with_forced_colors(text, bg);
        assert!(config.forced_color_scheme.is_some());
        let scheme = config.forced_color_scheme.unwrap();
        assert_eq!(scheme.text_color.r, 255);
        assert_eq!(scheme.text_color.g, 255);
        assert_eq!(scheme.background_color.b, 128);
    }

    #[test]
    fn test_default_config_has_no_forced_colors() {
        let config = RenderConfig::default();
        assert!(config.forced_color_scheme.is_none());
    }

    #[test]
    fn test_render_config_per_feature_aa_defaults() {
        let config = RenderConfig::default();
        assert!(config.text_antialiasing);
        assert!(config.path_antialiasing);
        assert!(config.image_antialiasing);
    }

    #[test]
    fn test_render_config_with_path_antialiasing_false_builder() {
        let config = RenderConfig::default().with_path_antialiasing(false);
        assert!(!config.path_antialiasing);
        // Other per-feature AA flags should remain at defaults
        assert!(config.text_antialiasing);
        assert!(config.image_antialiasing);
    }
}