Merge pull request #1132 from image-rs/next

Promotes next to master branch

.travis.yml

@@ -20,11 +20,12 @@ env:
   matrix:
     - DEFAULT_FEATURES='yes'
     - FEATURES=''
-    - FEATURES='gif_codec'
+    - FEATURES='gif'
     - FEATURES='jpeg'
-    - FEATURES='png_codec'
+    - FEATURES='png'
     - FEATURES='pnm'
     - FEATURES='tga'
+    - FEATURES='dds'
     - FEATURES='tiff'
     - FEATURES='webp'
     - FEATURES='hdr'
@@ -51,6 +52,14 @@ matrix:
       script:
         - rustup component add clippy
         - cargo clippy
+    - os: linux
+      rust: nightly
+      name: "Public private dependencies"
+      script:
+        - mv ./Cargo.toml.public-private-dependencies ./Cargo.toml
+        - echo "#![deny(exported_private_dependencies)]" | cat - src/lib.rs > src/lib.rs.0
+        - mv src/lib.rs.0 src/lib.rs
+        - cargo check
 script:
   - if [ -n "${FEATURES+exists}" ]; then
       cargo build -v --no-default-features --features "$FEATURES" &&
@@ -60,3 +69,7 @@ script:
   - if [ -n "${DEFAULT_FEATURES+exists}" ]; then
       cargo test -v;
     fi
+  - if [ "$TRAVIS_RUST_VERSION" == "nightly" ] && [ -n "${DEFAULT_FEATURES+exists}" ]; then
+      cargo build -v --features=benchmarks &&
+      cargo build -v --benches --features=benchmarks;
+    fi

CHANGES.md

@@ -8,6 +8,54 @@ Rust image aims to be a pure-Rust implementation of various popular image format
 
 ## Changes
 
+### Version 0.23.0-preview.0
+
+This major release intends to improve the interface with regards to handling of
+color format data for both decoding and encoding. This necessitated many
+breaking changes anyways so it was used to improve the compliance to the
+interface guidelines such as outstanding renaming.
+
+WIP: This preview version is intended to allow an evaluation and feedback on
+the new interface. It is not yet perfect with regards to color spaces but it
+was designed mainly as an improvement over the current interface with regards
+to in-memory color formats, first. We'll get to color spaces in a later major
+version.
+
+- Heavily reworked `ColorType`:
+  - This type is now used for denoting formats for which we support operations
+      on buffers in these memory representations. Particularly, all channels in
+      pixel types are assumed to be an integer number of bytes (In terms of the
+      Rust type system, these are `Sized` and one can crate slices of channel
+      values).
+  - An `ExtendedColorType` (WIP: do You have better name?) is used to express
+      more generic color formats for which the library has limited support but
+      can be converted/scaled/mapped into a `ColorType` buffer. This operation
+      might be fallible but, for example, includes sources with 1/2/4-bit
+      components.
+  - Both types are non-exhaustive to add more formats in a minor release.
+  - A work-in-progress (#1085) will further separate the color model from the
+      specific channel instantiation, e.g. both `8-bit RGB` and `16-bit BGR`
+      are instantiations of `RGB` color model.
+- Reworked the `ImageDecoder` trait:
+  - `read_image` takes an output buffer argument instead of allocating all
+      memory on its own.
+  - The return type of `dimensions` now aligns with `GenericImage` sizes.
+  - The `colortype` method was renamed to `color_type` for conformity.
+- The result of `encode` operations is now uniformly an `ImageResult<()>`.
+- Removed public converters from some `tiff` and `png` types. This allows
+  upgrading the dependency across major versions without a major release in
+  `image` itself.
+- The enums `ColorType`, `DynamicImage`, `imageops::FilterType`, `ImageFormat`
+  no longer re-export all of their variants in the top-level of the crate. This
+  removes the growing pollution in the documentation and usage.
+- The capitalization of types such as `HDRDecoder` etc. has been adjusted to
+  adhere to the API guidelines. These are now spelled `HdrDecoder` etc. The
+  same change has been made on `ImageFormat` and other enum variants.
+- The `Progress` type has finally received public access functions. Strange
+  that no one reported them missing.
+- Introduced `PixelDensity` and `PixelDensityUnit` to store DPI information in
+  formats that support encoding this form of metadata (e.g. in `jpeg`).
+
 ### Version 0.22.5
 
 - Added `GenericImage::copy_within`, specialized for `ImageBuffer`

Cargo.toml

@@ -1,21 +1,13 @@
 [package]
 name = "image"
-version = "0.22.5"
+version = "0.23.0-preview.0"
+edition = "2018"
 license = "MIT"
 description = "Imaging library written in Rust. Provides basic filters and decoders for the most common image formats."
-authors = [
-    "ccgn",
-    "bvssvni <bvssvni@gmail.com>",
-    "nwin",
-    "TyOverby <ty@pre-alpha.com>",
-    "HeroicKatora",
-    "Calum",
-    "CensoredUsername <cens.username@gmail.com>",
-    "fintelia <fintelia@gmail.com>"
-]
+authors = ["The image-rs Developers"]
 readme = "README.md"
 documentation = "https://docs.rs/image"
-repository = "https://github.com/image-rs/image.git"
+repository = "https://github.com/image-rs/image"
 homepage = "https://github.com/image-rs/image"
 categories = ["multimedia::images", "multimedia::encoding"]
 exclude = [
@@ -29,31 +21,16 @@ name = "image"
 path = "./src/lib.rs"
 
 [dependencies]
-byteorder = "1.2.1"
+bytemuck = "1"
+byteorder = "1.3.2"
 num-iter = "0.1.32"
 num-rational = { version = "0.2.1", default-features = false }
 num-traits = "0.2.0"
-
-[dependencies.gif]
-version = "0.10.0"
-optional = true
-
-[dependencies.jpeg-decoder]
-version = "0.1"
-default-features = false
-optional = true
-
-[dependencies.png]
-version = "0.15"
-optional = true
-
-[dependencies.scoped_threadpool]
-version = "0.1"
-optional = true
-
-[dependencies.tiff]
-version = "0.3.1"
-optional = true
+gif = { version = "0.10.0", optional = true }
+jpeg = { package = "jpeg-decoder", version = "0.1", default-features = false, optional = true }
+png = { version = "0.15.2", optional = true }
+scoped_threadpool = { version = "0.1", optional = true }
+tiff = { version = "0.4.0", optional = true }
 
 [dev-dependencies]
 crc32fast = "1.2.0"
@@ -62,18 +39,16 @@ glob = "0.3"
 quickcheck = "0.9"
 
 [features]
-default = ["gif_codec", "jpeg", "ico", "png_codec", "pnm", "tga", "tiff", "webp", "bmp", "hdr", "dxt", "jpeg_rayon"]
+default = ["gif", "jpeg", "ico", "png", "pnm", "tga", "tiff", "webp", "bmp", "hdr", "dxt", "dds", "jpeg_rayon"]
 
-gif_codec = ["gif"]
-ico = ["bmp", "png_codec"]
-jpeg = ["jpeg-decoder"]
-png_codec = ["png"]
+ico = ["bmp", "png"]
 pnm = []
 tga = []
 webp = []
 bmp = []
 hdr = ["scoped_threadpool"]
 dxt = []
-jpeg_rayon = ["jpeg-decoder/rayon"]
+dds = ["dxt"]
+jpeg_rayon = ["jpeg/rayon"]
 
 benchmarks = []

Cargo.toml.public-private-dependencies

@@ -0,0 +1,58 @@
+cargo-features = ["public-dependency"]
+
+[package]
+name = "image"
+version = "0.23.0-preview.0"
+edition = "2018"
+license = "MIT"
+description = "Imaging library written in Rust. Provides basic filters and decoders for the most common image formats."
+authors = ["The image-rs Developers"]
+readme = "README.md"
+documentation = "https://docs.rs/image"
+repository = "https://github.com/image-rs/image"
+homepage = "https://github.com/image-rs/image"
+categories = ["multimedia::images", "multimedia::encoding"]
+exclude = [
+    "src/png/testdata/*",
+    "examples/*",
+    "tests/*",
+]
+
+[lib]
+name = "image"
+path = "./src/lib.rs"
+
+[dependencies]
+# Not yet public.
+bytemuck = "1"
+byteorder = "1.3.2"
+num-iter = "0.1.32"
+num-rational = "0.2.1"
+# Public due to Pixel, otherwise quite useless.
+num-traits = { version = "0.2.0", public = true }
+gif = { version = "0.10.0", optional = true }
+jpeg = { package = "jpeg-decoder", version = "0.1", default-features = false, optional = true }
+png = { version = "0.15.2", optional = true }
+scoped_threadpool = { version = "0.1", optional = true }
+tiff = { version = "0.4.0", optional = true }
+
+[dev-dependencies]
+crc32fast = "1.2.0"
+num-complex = "0.2.0"
+glob = "0.3"
+quickcheck = "0.9"
+
+[features]
+default = ["gif", "jpeg", "ico", "png", "pnm", "tga", "tiff", "webp", "bmp", "hdr", "dxt", "dds", "jpeg_rayon"]
+
+ico = ["bmp", "png"]
+pnm = []
+tga = []
+webp = []
+bmp = []
+hdr = ["scoped_threadpool"]
+dxt = []
+dds = ["dxt"]
+jpeg_rayon = ["jpeg/rayon"]
+
+benchmarks = []

README.md

@@ -29,14 +29,17 @@ https://docs.rs/image
 | WebP   | Lossy(Luma channel only) | No |
 | PNM    | PBM, PGM, PPM, standard PAM | Yes |
 
-### 2.2 The ```ImageDecoder``` Trait
-All image format decoders implement the ```ImageDecoder``` trait which provides the following methods:
-+ **dimensions**: Return a tuple containing the width and height of the image
-+ **colortype**: Return the color type of the image.
-+ **row_len**: Returns the length in bytes of one decoded row of the image
-+ **read_scanline**: Read one row from the image into buf Returns the row index
-+ **read_image**: Decode the entire image and return it as a Vector
-+ **load_rect**: Decode a specific region of the image
+### 2.2 The ```ImageDecoder``` and ```ImageDecoderExt` Traits
+
+All image format decoders implement the ```ImageDecoder``` trait which provide
+basic methods for getting image metadata and decoding images. Some formats
+additionally provide ```ImageDecoderExt``` implementations which allow for
+decoding only part of an image at once.
+
+The most important methods for decoders are...
++ **dimensions**: Return a tuple containing the width and height of the image.
++ **color_type**: Return the color type of the image data produced by this decoder.
++ **read_image**: Decode the entire image and return it as a Vec of bytes.
 
 ## 3 Pixels
 ```image``` provides the following pixel types:
@@ -249,7 +252,7 @@ fn main() {
     let buffer: &[u8] = unimplemented!(); // Generate the image data
 
     // Save the buffer as "image.png"
-    image::save_buffer("image.png", buffer, 800, 600, image::RGB(8)).unwrap()
+    image::save_buffer("image.png", buffer, 800, 600, image::ColorType::Rgb8).unwrap()
 }
 
 ```

benches/encode_jpeg.rs

@@ -21,10 +21,10 @@ fn run_benchmark(b: &mut Bencher, color_type: image::ColorType) {
 
 #[bench]
 fn bench_rgb(b: &mut Bencher) {
-    run_benchmark(b, image::RGB(8));
+    run_benchmark(b, image::ColorType::Rgb8);
 }
 
 #[bench]
 fn bench_gray(b: &mut Bencher) {
-    run_benchmark(b, image::Gray(8));
+    run_benchmark(b, image::ColorType::L8);
 }

benches/load.rs

@@ -16,7 +16,7 @@ struct BenchDef<'a> {
 const IMAGE_DIR: [&'static str; 3] = [".", "tests", "images"];
 const BMP: BenchDef<'static> = BenchDef {
     dir: &["bmp", "images"],
-    format: ImageFormat::BMP,
+    format: ImageFormat::Bmp,
 };
 
 fn bench_load(b: &mut test::Bencher, def: &BenchDef, filename: &str) {

examples/opening.rs

@@ -5,7 +5,7 @@ use std::env;
 use std::fs::File;
 use std::path::Path;
 
-use image::GenericImageView;
+use image::{ImageFormat, GenericImageView};
 
 fn main() {
     let file = if env::args().count() == 2 {
@@ -27,5 +27,5 @@ fn main() {
     let fout = &mut File::create(&Path::new(&format!("{}.png", file))).unwrap();
 
     // Write the contents of this image to the Writer in PNG format.
-    im.write_to(fout, image::PNG).unwrap();
+    im.write_to(fout, ImageFormat::Png).unwrap();
 }

examples/scaledown/main.rs

@@ -1,6 +1,7 @@
 extern crate image;
 
-use image::{FilterType, PNG};
+use image::ImageFormat;
+use image::imageops::FilterType;
 use std::fmt;
 use std::fs::File;
 use std::time::{Duration, Instant};
@@ -39,14 +40,14 @@ fn main() {
         let scaled = img.resize(400, 400, filter);
         println!("Scaled by {} in {}", name, Elapsed::from(&timer));
         let mut output = File::create(&format!("test-{}.png", name)).unwrap();
-        scaled.write_to(&mut output, PNG).unwrap();
+        scaled.write_to(&mut output, ImageFormat::Png).unwrap();
     }
 
     for size in &[20_u32, 40, 100, 200, 400] {
         let timer = Instant::now();
         let scaled = img.thumbnail(*size, *size);
         println!("Thumbnailed to {} in {}", size, Elapsed::from(&timer));
         let mut output = File::create(format!("test-thumb{}.png", size)).unwrap();
-        scaled.write_to(&mut output, PNG).unwrap();
+        scaled.write_to(&mut output, ImageFormat::Png).unwrap();
     }
 }

examples/scaleup/main.rs

@@ -1,6 +1,7 @@
 extern crate image;
 
-use image::{FilterType, PNG};
+use image::ImageFormat;
+use image::imageops::FilterType;
 use std::fmt;
 use std::fs::File;
 use std::time::{Duration, Instant};
@@ -39,12 +40,12 @@ fn main() {
         let scaled = tiny.resize(32, 32, filter);
         println!("Scaled by {} in {}", name, Elapsed::from(&timer));
         let mut output = File::create(&format!("up2-{}.png", name)).unwrap();
-        scaled.write_to(&mut output, PNG).unwrap();
+        scaled.write_to(&mut output, ImageFormat::Png).unwrap();
 
         let timer = Instant::now();
         let scaled = tiny.resize(48, 48, filter);
         println!("Scaled by {} in {}", name, Elapsed::from(&timer));
         let mut output = File::create(&format!("up3-{}.png", name)).unwrap();
-        scaled.write_to(&mut output, PNG).unwrap();
+        scaled.write_to(&mut output, ImageFormat::Png).unwrap();
     }
 }