Restore manganis optimizations (#3195)

* Create a crate for constant serialization of config structs for manganis * use SerializeConst for the image asset builder * switch to a declarative macro for assets * add serializable options for each asset type * implement the new manganis macro * optimize assets in the CLI * Fix assets with dioxus formattable * reduce fuzzing test limits * use the new syntax in examples * fix avif support * Fix manganis doc tests * cache asset optimization * Split out asset and bundled asset * make hash pointer width independent * Fix manganis macro docs * add constvec::is_empty method to fix clippy lint * remove nasm feature * simplify test_rsplit_once test so typos passes * revert example change from clippy fix * always accept unix paths * fix windows path seperator * fix folder asset hash * Optimize assets in a blocking task * Fix asset options docs * Document Asset and BundledAsset * simplify the linker macro a bit * add more docs to AssetParser expansion * add image format helpers * Split by both unix and windows path separators and take the smallest one
2024-11-26 18:12:24 +01:00
1 parent 31d72db82d
commit f9617c8d33
@@ -0,0 +1,225 @@
+use const_serialize::SerializeConst;
+
+use crate::AssetOptions;
+
+/// The type of an image. You can read more about the tradeoffs between image formats [here](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types)
+#[derive(
+    Debug,
+    PartialEq,
+    PartialOrd,
+    Clone,
+    Copy,
+    Hash,
+    SerializeConst,
+    serde::Serialize,
+    serde::Deserialize,
+)]
+#[repr(u8)]
+pub enum ImageFormat {
+    /// A png image. Png images cannot contain transparency and tend to compress worse than other formats
+    Png,
+    /// A jpg image. Jpg images can contain transparency and tend to compress better than png images
+    Jpg,
+    /// A webp image. Webp images can contain transparency and tend to compress better than jpg images
+    Webp,
+    /// An avif image. Avif images can compress slightly better than webp images but are not supported by all browsers
+    Avif,
+    /// An unknown image type
+    Unknown,
+}
+
+/// The size of an image asset
+#[derive(
+    Debug,
+    PartialEq,
+    PartialOrd,
+    Clone,
+    Copy,
+    Hash,
+    SerializeConst,
+    serde::Serialize,
+    serde::Deserialize,
+)]
+#[repr(C, u8)]
+pub enum ImageSize {
+    /// A manual size in pixels
+    Manual {
+        /// The width of the image in pixels
+        width: u32,
+        /// The height of the image in pixels
+        height: u32,
+    },
+    /// The size will be automatically determined from the image source
+    Automatic,
+}
+
+/// Options for an image asset
+#[derive(
+    Debug,
+    PartialEq,
+    PartialOrd,
+    Clone,
+    Copy,
+    Hash,
+    SerializeConst,
+    serde::Serialize,
+    serde::Deserialize,
+)]
+pub struct ImageAssetOptions {
+    ty: ImageFormat,
+    low_quality_preview: bool,
+    size: ImageSize,
+    preload: bool,
+}
+
+impl Default for ImageAssetOptions {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl ImageAssetOptions {
+    /// Create a new image asset options
+    pub const fn new() -> Self {
+        Self {
+            ty: ImageFormat::Unknown,
+            low_quality_preview: false,
+            size: ImageSize::Automatic,
+            preload: false,
+        }
+    }
+
+    /// Make the asset preloaded
+    ///
+    /// Preloading an image will make the image start to load as soon as possible. This is useful for images that will be displayed soon after the page loads or images that may not be visible immediately, but should start loading sooner
+    ///
+    /// ```rust
+    /// # use manganis::{asset, Asset, ImageAssetOptions};
+    /// const _: Asset = asset!("/assets/image.png", ImageAssetOptions::new().with_preload(true));
+    /// ```
+    pub const fn with_preload(self, preload: bool) -> Self {
+        Self { preload, ..self }
+    }
+
+    /// Check if the asset is preloaded
+    pub const fn preloaded(&self) -> bool {
+        self.preload
+    }
+
+    /// Sets the format of the image
+    ///
+    /// Choosing the right format can make your site load much faster. Webp and avif images tend to be a good default for most images
+    ///
+    /// ```rust
+    /// # use manganis::{asset, Asset, ImageAssetOptions, ImageFormat};
+    /// const _: Asset = asset!("/assets/image.png", ImageAssetOptions::new().with_format(ImageFormat::Webp));
+    /// ```
+    pub const fn with_format(self, format: ImageFormat) -> Self {
+        Self { ty: format, ..self }
+    }
+
+    /// Sets the format of the image to [`ImageFormat::Avif`]
+    ///
+    /// Avif images tend to be a good default for most images rendered in browser because
+    /// they compress images well
+    ///
+    /// ```rust
+    /// # use manganis::{asset, Asset, ImageAssetOptions, ImageFormat};
+    /// const _: Asset = asset!("/assets/image.png", ImageAssetOptions::new().with_avif());
+    /// ```
+    pub const fn with_avif(self) -> Self {
+        self.with_format(ImageFormat::Avif)
+    }
+
+    /// Sets the format of the image to [`ImageFormat::Webp`]
+    ///
+    /// Webp images tend to be a good default for most images rendered in browser because
+    /// they compress images well
+    ///
+    /// ```rust
+    /// # use manganis::{asset, Asset, ImageAssetOptions, ImageFormat};
+    /// const _: Asset = asset!("/assets/image.png", ImageAssetOptions::new().with_webp());
+    /// ```
+    pub const fn with_webp(self) -> Self {
+        self.with_format(ImageFormat::Webp)
+    }
+
+    /// Sets the format of the image to [`ImageFormat::Jpg`]
+    ///
+    /// Jpeg images compress much better than [`ImageFormat::Png`], but worse than [`ImageFormat::Webp`] or [`ImageFormat::Avif`]
+    ///
+    /// ```rust
+    /// # use manganis::{asset, Asset, ImageAssetOptions, ImageFormat};
+    /// const _: Asset = asset!("/assets/image.png", ImageAssetOptions::new().with_jpg());
+    /// ```
+    pub const fn with_jpg(self) -> Self {
+        self.with_format(ImageFormat::Jpg)
+    }
+
+    /// Sets the format of the image to [`ImageFormat::Png`]
+    ///
+    /// Png images don't compress very well, so they are not recommended for large images
+    ///
+    /// ```rust
+    /// # use manganis::{asset, Asset, ImageAssetOptions, ImageFormat};
+    /// const _: Asset = asset!("/assets/image.png", ImageAssetOptions::new().with_png());
+    /// ```
+    pub const fn with_png(self) -> Self {
+        self.with_format(ImageFormat::Png)
+    }
+
+    /// Get the format of the image
+    pub const fn format(&self) -> ImageFormat {
+        self.ty
+    }
+
+    /// Sets the size of the image
+    ///
+    /// If you only use the image in one place, you can set the size of the image to the size it will be displayed at. This will make the image load faster
+    ///
+    /// ```rust
+    /// # use manganis::{asset, Asset, ImageAssetOptions, ImageSize};
+    /// const _: Asset = asset!("/assets/image.png", ImageAssetOptions::new().with_size(ImageSize::Manual { width: 512, height: 512 }));
+    /// ```
+
+    pub const fn with_size(self, size: ImageSize) -> Self {
+        Self { size, ..self }
+    }
+
+    /// Get the size of the image
+    pub const fn size(&self) -> ImageSize {
+        self.size
+    }
+
+    // LQIP is currently disabled until we have the CLI set up to inject the low quality image preview after the crate is built through the linker
+    // /// Make the image use a low quality preview
+    // ///
+    // /// A low quality preview is a small version of the image that will load faster. This is useful for large images on mobile devices that may take longer to load
+    // ///
+    // /// ```rust
+    // /// # use manganis::{asset, Asset, ImageAssetOptions};
+    // /// const _: Asset = manganis::asset!("/assets/image.png", ImageAssetOptions::new().with_low_quality_image_preview());
+    // /// ```
+    //
+    // pub const fn with_low_quality_image_preview(self, low_quality_preview: bool) -> Self {
+    //     Self {
+    //         low_quality_preview,
+    //         ..self
+    //     }
+    // }
+
+    /// Convert the options into options for a generic asset
+    pub const fn into_asset_options(self) -> AssetOptions {
+        AssetOptions::Image(self)
+    }
+
+    pub(crate) const fn extension(&self) -> Option<&'static str> {
+        match self.ty {
+            ImageFormat::Png => Some("png"),
+            ImageFormat::Jpg => Some("jpg"),
+            ImageFormat::Webp => Some("webp"),
+            ImageFormat::Avif => Some("avif"),
+            ImageFormat::Unknown => None,
+        }
+    }
+}