From 0c7203a7e68e39ee72b2e5395ce0a84c07a8abc1 Mon Sep 17 00:00:00 2001 From: Matteo Paonessa Date: Fri, 11 Oct 2024 14:32:51 +0200 Subject: [PATCH] Better documentation --- README.md | 2 +- src/lib.rs | 72 +++++++++++++++++++++++++++++++++++++++++++++++ src/parameters.rs | 59 +++++++++++++++++++++++++++++++++++++- 3 files changed, 131 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cc13a2f..f2a4829 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ Libcaesium is a simple library performing JPEG, PNG, WebP and GIF (experimental) compression/optimization written in Rust, with a C interface. -> [!CAUTION] +> [!WARNING] > starting from v0.6.0 the library is written in Rust and no longer in C. There's a C interface, but it's not backward > compatible with the <0.6.0. diff --git a/src/lib.rs b/src/lib.rs index 69f90c0..af2f0b4 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -26,6 +26,17 @@ mod webp; mod convert; pub mod parameters; +/// Compresses an image file from the input path and writes the compressed image to the output path. +/// +/// # Arguments +/// +/// * `input_path` - A string representing the path to the input image file. +/// * `output_path` - A string representing the path to the output compressed image file. +/// * `parameters` - A reference to `CSParameters` containing compression settings. +/// +/// # Returns +/// +/// * `Result<(), CaesiumError>` - Returns `Ok(())` if compression is successful, otherwise returns a `CaesiumError`. pub fn compress( input_path: String, output_path: String, @@ -66,6 +77,16 @@ pub fn compress( Ok(()) } +/// Compresses an image file in memory and returns the compressed image as a byte vector. +/// +/// # Arguments +/// +/// * `in_file` - A vector of bytes representing the input image file. +/// * `parameters` - A reference to `CSParameters` containing compression settings. +/// +/// # Returns +/// +/// * `Result, CaesiumError>` - Returns a vector of bytes representing the compressed image if successful, otherwise returns a `CaesiumError`. pub fn compress_in_memory( in_file: Vec, parameters: &CSParameters, @@ -91,6 +112,19 @@ pub fn compress_in_memory( Ok(compressed_file) } +/// Compresses an image file in memory up to a specified size and returns the compressed image as a byte vector. +/// +/// # Arguments +/// +/// * `in_file` - A vector of bytes representing the input image file. +/// * `parameters` - A mutable reference to `CSParameters` containing compression settings. +/// * `max_output_size` - The maximum size of the output compressed image in bytes. +/// * `return_smallest` - A boolean indicating whether to return the smallest compressed image if the desired size is not achieved. +/// +/// # Returns +/// +/// * `Result, CaesiumError>` - Returns a vector of bytes representing the compressed image if successful, otherwise returns a `CaesiumError`. + pub fn compress_to_size_in_memory( in_file: Vec, parameters: &mut CSParameters, @@ -202,6 +236,19 @@ pub fn compress_to_size_in_memory( Ok(compressed_file) } +/// Compresses an image file from the input path up to a specified size and writes the compressed image to the output path. +/// +/// # Arguments +/// +/// * `input_path` - A string representing the path to the input image file. +/// * `output_path` - A string representing the path to the output compressed image file. +/// * `parameters` - A mutable reference to `CSParameters` containing compression settings. +/// * `max_output_size` - The maximum size of the output compressed image in bytes. +/// * `return_smallest` - A boolean indicating whether to return the smallest compressed image if the desired size is not achieved. +/// +/// # Returns +/// +/// * `Result<(), CaesiumError>` - Returns `Ok(())` if compression is successful, otherwise returns a `CaesiumError`. pub fn compress_to_size( input_path: String, output_path: String, @@ -237,6 +284,19 @@ pub fn compress_to_size( Ok(()) } +/// Converts an image file from the input path to a specified format and writes the converted image to the output path. +/// +/// # Arguments +/// +/// * `input_path` - A string representing the path to the input image file. +/// * `output_path` - A string representing the path to the output converted image file. +/// * `parameters` - A reference to `CSParameters` containing conversion settings. +/// * `format` - The target format to convert the image to. +/// +/// # Returns +/// +/// * `Result<(), CaesiumError>` - Returns `Ok(())` if conversion is successful, otherwise returns a `CaesiumError`. + pub fn convert(input_path: String, output_path: String, parameters: &CSParameters, format: SupportedFileTypes) -> error::Result<()> { let file_type = get_filetype_from_path(&input_path); @@ -269,6 +329,18 @@ pub fn convert(input_path: String, output_path: String, parameters: &CSParameter Ok(()) } + +/// Converts an image file in memory to a specified format and returns the converted image as a byte vector. +/// +/// # Arguments +/// +/// * `in_file` - A vector of bytes representing the input image file. +/// * `parameters` - A reference to `CSParameters` containing conversion settings. +/// * `format` - The target format to convert the image to. +/// +/// # Returns +/// +/// * `Result, CaesiumError>` - Returns a vector of bytes representing the converted image if successful, otherwise returns a `CaesiumError`. pub fn convert_in_memory(in_file: Vec, parameters: &CSParameters, format: SupportedFileTypes) -> Result, CaesiumError> { convert::convert_in_memory(in_file, format, parameters) } diff --git a/src/parameters.rs b/src/parameters.rs index 755010c..4039a43 100644 --- a/src/parameters.rs +++ b/src/parameters.rs @@ -1,5 +1,12 @@ use crate::parameters::TiffCompression::Deflate; +/// Enum representing different chroma subsampling options for JPEG compression. +/// +/// - `CS444`: 4:4:4 chroma subsampling +/// - `CS422`: 4:2:2 chroma subsampling +/// - `CS420`: 4:2:0 chroma subsampling +/// - `CS411`: 4:1:1 chroma subsampling +/// - `Auto`: Automatic chroma subsampling #[derive(Copy, Clone, PartialEq)] pub enum ChromaSubsampling { CS444, @@ -9,6 +16,12 @@ pub enum ChromaSubsampling { Auto, } +/// Enum representing different compression algorithms for TIFF images. +/// +/// - `Uncompressed`: No compression +/// - `Lzw`: LZW compression +/// - `Deflate`: Deflate compression +/// - `Packbits`: PackBits compression #[derive(Copy, Clone, PartialEq)] pub enum TiffCompression { Uncompressed = 0, @@ -17,19 +30,37 @@ pub enum TiffCompression { Packbits = 3, } +/// Enum representing different deflate levels for TIFF compression. +/// +/// - `Fast`: Fast compression +/// - `Balanced`: Balanced compression +/// - `Best`: Best compression #[derive(Copy, Clone, PartialEq)] pub enum TiffDeflateLevel { Fast = 1, Balanced = 6, Best = 9, } + +/// Struct representing parameters for JPEG compression. +/// +/// Fields: +/// - `quality`: Quality of the JPEG image (0-100) +/// - `chroma_subsampling`: Chroma subsampling option +/// - `progressive`: Whether to use progressive JPEG #[derive(Copy, Clone)] pub struct JpegParameters { pub quality: u32, pub chroma_subsampling: ChromaSubsampling, - pub progressive: bool + pub progressive: bool, } +/// Struct representing parameters for PNG compression. +/// +/// Fields: +/// - `quality`: Quality of the PNG image (0-100) +/// - `force_zopfli`: Whether to force the use of Zopfli compression (can be very slow) +/// - `optimization_level`: Optimization level for PNG compression (0-6) #[derive(Copy, Clone)] pub struct PngParameters { pub quality: u32, @@ -37,22 +68,48 @@ pub struct PngParameters { pub optimization_level: u8, } +/// Struct representing parameters for GIF compression. +/// +/// Fields: +/// - `quality`: Quality of the GIF image (0-100) #[derive(Copy, Clone)] pub struct GifParameters { pub quality: u32, } +/// Struct representing parameters for WebP compression. +/// +/// Fields: +/// - `quality`: Quality of the WebP image (0-100) #[derive(Copy, Clone)] pub struct WebPParameters { pub quality: u32, } +/// Struct representing parameters for TIFF compression. +/// +/// Fields: +/// - `algorithm`: Compression algorithm for TIFF +/// - `deflate_level`: Deflate level for TIFF compression #[derive(Copy, Clone)] pub struct TiffParameters { pub algorithm: TiffCompression, pub deflate_level: TiffDeflateLevel, } +/// Struct representing overall compression parameters. +/// +/// Fields: +/// - `jpeg`: JPEG compression parameters +/// - `png`: PNG compression parameters +/// - `gif`: GIF compression parameters +/// - `webp`: WebP compression parameters +/// - `tiff`: TIFF compression parameters +/// - `keep_metadata`: Whether to keep metadata in the compressed image +/// - `optimize`: Whether to use lossless compression +/// - `width`: Width of the output image +/// - `height`: Height of the output image +/// - `output_size`: Desired output size of the compressed image #[derive(Copy, Clone)] pub struct CSParameters { pub jpeg: JpegParameters,