add public resize_to_fit and resize_to_fill utility functions

[filnet]

Proposed API would look like this:

/// Resizes the given size to fit into a new size while preserving the aspect ratio.
/// The returned size can be smaller than the requested size in one or the other dimension.
pub fn resize_to_fit(size: (u32, u32), new_size: (u32, u32)) -> (u32, u32) {
    resize_dimensions(size.0, size.1, new_size.0, new_size.1, false)
}

/// Resizes the given size to fill a new size while preserving the aspect ratio.
/// The returned size can be larger than the requested size in one or the other dimension.
pub fn resize_to_fill(size: (u32, u32), new_size: (u32, u32)) -> (u32, u32) {
    resize_dimensions(size.0, size.1, new_size.0, new_size.1, true)
}

Feel free to comment/suggest alternatives.

If this API is validated, I'll rewrite the functions to get rid of the old resize_dimensions function.

[fintelia]

I'd probably word this "Returns the dimensions..." Using the word "Resize" makes it sound like the function actually resamples a specific image.

[filnet]

Yes, I have been rewriting that sentence a few times... And English is not my mother tongue.
Feel free to suggest a full sentence.

[fintelia]

How about:

Returns the dimensions of the largest possible image that would fit inside a canvas of canvas_size, while keeping the same aspect ratio from original_size. The returned size will be smaller than the canvas size in at most one dimension.

fn dimensions_to_fit_canvas(original_size: (u32, u32), canvas_size: (u32, u32)) -> (u32, u32) {...}

[filnet]

Trouble with the use of canvas is that the fill mode can return a size larger than the canvas.
The same problem affects @HeroicKatora's suggestion to use cover. cover will crop enlarged images to fit the canvas.
But the current fill mode will not crop. Might be confusing...

DynImage::resize_to_fit() will actually fill then crop, meaning fill is still needed.

I also did a bit of searching for prior art.
The best I found so far is https://legacy.imagemagick.org/Usage/resize/#resize. It does not exhibit a usable API but lists all the resize modes possible and provides wording.
I was hoping to find something immediately adoptable but no luck so far.

Anyways, to move on, what about introducing the enum suggested by @HeroicKatora :

fn dimensions_to_fit_canvas(original_size: (u32, u32), canvas_size: (u32, u32), resize_mode: ResizeMode) -> (u32, u32) {...}

Where ResizeMode can be :

• FIT (or CONTAIN)
• FILL (or COVER)
• FILL_OVERFLOW (or COVER_NO_CROP) // current fill mode

Might be a bit over engineered and does not address the canvas/background-size issues though...

[filnet]

Note that DynImage::resize_to_fill() has a slightly different behavior.
In addition to resizing it will also crop the image so that it does not exceed the new dimensions.

[HeroicKatora]

In css these size specifiers are called contain and cover instead of fit and fill. Those are relatively clear and pretty popular prior art.

[HeroicKatora]

I'd just implement them here instead of in utils and not re-export them to have them visible in two places.

[filnet]

I am sleeping on it for a bit. I don't like to force solutions.

I'll do another round of prior art research and will come back with another proposal.

[HeroicKatora]

@filnet Did you find the time for the research :)