From 574952f578ac32b6a7e6fb571df81650ac6fc8eb Mon Sep 17 00:00:00 2001 From: Laurenz Date: Thu, 30 Jan 2025 17:47:27 +0100 Subject: [PATCH] A bit of docs --- .../typst-library/src/visualize/image/mod.rs | 49 +++++++++++++------ .../src/visualize/image/pixmap.rs | 13 +++-- tests/suite/visualize/image.typ | 2 +- 3 files changed, 40 insertions(+), 24 deletions(-) diff --git a/crates/typst-library/src/visualize/image/mod.rs b/crates/typst-library/src/visualize/image/mod.rs index b6710fc93..80dc1fa53 100644 --- a/crates/typst-library/src/visualize/image/mod.rs +++ b/crates/typst-library/src/visualize/image/mod.rs @@ -48,9 +48,19 @@ use crate::World; /// ``` #[elem(scope, Show, LocalName, Figurable)] pub struct ImageElem { - /// A path to an image file or raw bytes making up an encoded image. + /// The source to load the image from. Either of: /// - /// For more details about paths, see the [Paths section]($syntax/#paths). + /// - A path to an image file. For more details about paths, see the [Paths + /// section]($syntax/#paths). + /// - Raw bytes making up an encoded image. + /// - A dictionary with the following keys: + /// - `data` ([bytes]): Raw pixel data in the specified [`format`]($image.format). + /// - `pixel-width` ([int]): The width in pixels. + /// - `pixel-height` ([int]): The height in pixels. + /// - `icc-profile` ([bytes], optional): An ICC profile for the image. + /// + /// The width multiplied by the height multiplied by the channel count for + /// the specified format must match the data length. #[required] #[parse( let source = args.expect::>("source")?; @@ -61,8 +71,11 @@ pub struct ImageElem { /// The image's format. Detected automatically by default. /// - /// Supported formats are PNG, JPEG, GIF, and SVG. Using a PDF as an image + /// Supported image formats are PNG, JPEG, GIF, and SVG. Using a PDF as an image /// is [not currently supported](https://github.com/typst/typst/issues/145). + /// + /// Aside from these encoded image formats, Typst also lets you provide raw + /// image data as the source. In this case, providing a format is mandatory. pub format: Smart, /// The width of the image. @@ -88,17 +101,20 @@ pub struct ImageElem { #[default(ImageFit::Cover)] pub fit: ImageFit, + /// A hint to viewers how they should scale the image. + /// + /// When set to `{auto}`, the default is left up to the viewer. For PNG + /// export, Typst will default to smooth scaling, like most PDF and SVG + /// viewers. + /// + /// _Note:_ The exact look may differ across PDF viewers. + pub scaling: Smart, + /// Whether text in SVG images should be converted into curves before /// embedding. This will result in the text becoming unselectable in the /// output. #[default(false)] pub flatten_text: bool, - - /// A hint to the viewer how it should scale the image. - /// - /// _Note:_ This option may be ignored and results look different depending - /// on the format and viewer. - pub scaling: Smart, } #[scope] @@ -139,12 +155,13 @@ impl ImageElem { /// How the image should adjust itself to a given area. #[named] fit: Option, - /// Whether text in SVG images should be converted into paths. - #[named] - flatten_text: Option, - /// How the image should be scaled by the viewer. + /// A hint to viewers how they should scale the image. #[named] scaling: Option>, + /// Whether text in SVG images should be converted into curves before + /// embedding. + #[named] + flatten_text: Option, ) -> StrResult { let bytes = data.into_bytes(); let source = @@ -450,9 +467,9 @@ cast! { /// The image scaling algorithm a viewer should use. #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Cast)] pub enum ImageScaling { - /// Scale photos with a smoothing algorithm such as bilinear interpolation. + /// Scale with a smoothing algorithm such as bilinear interpolation. Smooth, - /// Scale with nearest neighbor or similar to preserve the pixelated look - /// of the image. + /// Scale with nearest neighbor or a similar algorithm to preserve the + /// pixelated look of the image. Pixelated, } diff --git a/crates/typst-library/src/visualize/image/pixmap.rs b/crates/typst-library/src/visualize/image/pixmap.rs index 6a474c37b..f8154c497 100644 --- a/crates/typst-library/src/visualize/image/pixmap.rs +++ b/crates/typst-library/src/visualize/image/pixmap.rs @@ -37,11 +37,11 @@ impl PixmapImage { .checked_mul(source.pixel_height) .and_then(|size| size.checked_mul(pixel_size)) else { - bail!("provided pixel dimensions are too large"); + bail!("pixel dimensions are too large"); }; if expected_size as usize != source.data.len() { - bail!("provided pixel dimensions and pixmap data do not match"); + bail!("pixel dimensions and pixel data do not match"); } Ok(Self(Arc::new(Repr { source, format }))) @@ -98,14 +98,13 @@ impl PixmapImage { /// Determines how the given image is interpreted and encoded. #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Cast)] pub enum PixmapFormat { - /// Red, green, and blue channels, one byte per channel. - /// No alpha channel. + /// Raw image data with three 8-bit channels: Red, green, blue. Rgb8, - /// Red, green, blue, and alpha channels, one byte per channel. + /// Raw image data with four 8-bit channels: Red, green, blue, alpha. Rgba8, - /// A single byte channel representing brightness. + /// Raw image data with one 8-bit channel: Brightness. Luma8, - /// Brightness and alpha, one byte per channel. + /// Raw image data with two 8-bit channels: Brightness and alpha. Lumaa8, } diff --git a/tests/suite/visualize/image.typ b/tests/suite/visualize/image.typ index 7869da556..9551ad047 100644 --- a/tests/suite/visualize/image.typ +++ b/tests/suite/visualize/image.typ @@ -190,7 +190,7 @@ A #box(image("/assets/images/tiger.jpg", height: 1cm, width: 80%)) B ) --- image-pixmap-invalid-size --- -// Error: 1:2-8:2 provided pixel dimensions and pixmap data do not match +// Error: 1:2-8:2 pixel dimensions and pixel data do not match #image( ( data: bytes((0x00, 0x00, 0x00)),