Added in-buffer scanline decoding API

[OtaK]

Hi!

I needed this personally for a project, so I'm submitting a (draft) PR for this feature.

• Added DecompressStarted::read_scanlines_into to do in-buffer scanline decoding
• Added DecompressStarted::read_scanlines_flat* APIs to do image crate-friendly scanline decoding

I'm still a bit unsure on how sound my code is, but it does work on my machine™️ for hours on end (it's used in a webcam capture + tensorflow ML inference project).

Most of the diff is rustfmt doing its thing anyway. I'll make a cleanup pass before marking the PR as reviewable :)

Thanks!

[kornelski]

Thanks for the PR. The functionality seems useful

[OtaK]

Okay, this PR took a bit of scale;

I separated the methods I needed with the ones that are in line with the crate's original API. The read_scanlines_flat* functions are meant to work with/produce flat buffers like the ones consumed by the image crate without needing to do post-processing or any kind of funky reordering/flattening.

There are now 2 big categories:

• Methods that produce/consume buffers of RGB(A) arrays (eg. [[r, g, b(, a)], [r, g, b(, a)], ...])
  • DecompressStarted::read_scanlines which returns a Vec<rgb::Pod>
  • DecompressStarted::read_scanlines_into for the non-allocating version, returns a bool indicating success or failure, and writes into a &mut [rgb::Pod]
• Methods that produce/consume flat RGB(A) bufffers (eg. [r, g, b(, a), r, g, b(, a), ...]) to interact with image
  • DecompressStarted::read_scanlines_flat which returns a Vec<u8>
  • DecompressStarted::read_scanlines_flat_into, non allocating version, returns a bool, writes into a &mut [u8]

I'm aware this does increase the API surface by a bit, but it's the best I could come up with as the existing API makes it extremely painful to produce data that is readily consumable by image.

[kornelski]

Yeah, that looks okay

[kornelski]

I've noticed the code has already been making slices from uninitialized data, and that's UB, so I'll have to fix that anyway.

[OtaK]

Maybe you noticed, I added a bit more tests in general to test the different ways to decode images (rgb, rgba, packed rgb, packed rgba formats). I didn't test the in-buffer methods directly since those methods are called internally by the allocating ones.

Those UB would be residing only in the non-flat functions right? Since the packed format requires a &mut [u8] this assumes that memory is initialized.

If you want I might take a shot at solving those UBs, but I'm concerned this would cause API breakage anyway.

[kornelski]

Thanks