New transformations

[aochagavia]

Hello there! I am using libpng for decoding images in a Rust codebase and am considering switching to this crate. Some transformations I'm using are not provided by the png crate at the moment, but I might be able to contribute with a PR if things are not too complex. Let's discuss possible implementation routes.

For context, here is the relevant code that uses libpng:

ffi::png_read_info(self.data, self.info);

// Normalise to unpacked BGRA
ffi::png_set_packing(self.data);
ffi::png_set_expand(self.data);
ffi::png_set_add_alpha(self.data, 0xff, ffi::PNG_FILLER_AFTER);
ffi::png_set_bgr(self.data);

// Adjust gamma if the value is unusual
let mut gamma: f64 = 0.0;
if ffi::png_get_gAMA(self.data, self.info, &mut gamma) != 0
    && (gamma - 1.0 / DEFAULT_GAMMA).abs() > DEFAULT_GAMMA_MARGIN
{
    ffi::png_set_gamma(self.data, DEFAULT_GAMMA, gamma);
}

ffi::png_set_scale_16(self.data);
ffi::png_read_update_info(self.data, self.info);

It looks like the following transformations are alrady available:

• png_set_expand -> Transformations::EXPAND
• png_set_add_alpha -> Transformations::ALPHA
• png_set_scale_16 -> Transformations::STRIP_16 (this is not an exact mapping, but the crate docs suggest the effect might be the same)

This means the following transformations are missing:

• png_set_packing
• png_set_bgr
• png_set_gamma

From this list, the first two seem straightforward (though maybe there are surprises lurking for me, since I'm not too well versed in png processing). The gamma one seems a bit more complicated. I don't see how it can fit the current Transformations architecture, because it takes parameters. Do you have any suggestions on how to tackle it?

By the way, if it's possible to implement these transformations outside of the library (i.e. in my own user code) without a performance impact, I'd be happy to try that too.

[197g]

• png_set_packing: sounds useful.
• png_set_bgr: probably comes with performance gains compared to an outside implementation, actually. If the individual samples are expanded or sampled from a palette then a combined function that also swaps the channel order will require much fewer memory bandwidth.
• png_set_gamma: ugh. The parameter wouldn't be the big problem, I just don't like 'gamma'. It becomes quite ill-defined with cicp chunks. Maybe this is only applied if the gAMA chunk itself is applied, i.e. it is not applied if there is other color information. As you may know (or glean from the docs), there are some special values that instead express sensible color space encoding of the target surface but those are only sRGB (because 2.2 is not fully correct), Mac18 (??), and linear. Overall, I think that whole option is better left to an actual CMS. Again, performance margins if you're using palettes as we can apply it to the palette instead of individual pixels in post-processing but maybe that should be handled with an interface that permits inline rewriting of a decoded palette instead of integrating a half-baked CMS into the library.

[aochagavia]

Thanks! I'll think about this some more and come back with PRs if I end up making the switch :)