Each scaling modes has unique behavior for different window-size to pixmap-size ratios.
Unfortunately, there are no universally applicable naming conventions for these modes.
In fact, different implementations tend to contradict each other.
Mode feature matrix
Mode
Aspect Ratio
Pixel Ratio
Cropping
Border
Comment(s)
none
preserved
preserved
yes
4
Crops if the window.size < pixmap.size.
stretch
no
no
no
none
contain
preserved
no
no
2
Letterboxing/Pillarboxing
integer
preserved
preserved
no
4
Works only if window.size >= pixmap.size.
intHybrid
preserved
when up
no
4 or 2
Hybrid: int upscaling, decimal downscaling
cover
preserved
no
yes
none
Integer scaling – Note that the resulting integer ratio of a window smaller than a pixmap is 0.
Use intHybrid to prevent the pixmap from disappearing on disproportionately small window sizes.
It uses integer-mode for upscaling and the regular contain-mode for downscaling.
Feature
Definition
Aspect Ratio
Whether the original aspect ratio (width ÷ height) of the input frame is preserved
Pixel Ratio
Whether the orignal pixel ratio (= square) is preserved
Cropping
Whether the outer areas of the input frame might get cut off
Border
The number of padding-areas/borders that can potentially appear around the frame
For your convience, aliases matching the `object-fit`
CSS property are provided, too. These are prefixed with css.
Currently there is no equivalent for scale-down as it does not appear to be particularly useful here.
Scaling/Fit Modes
Each scaling modes has unique behavior for different window-size to pixmap-size ratios.
Use intHybrid to prevent the pixmap from disappearing on disproportionately small window sizes. It uses integer-mode for upscaling and the regular contain-mode for downscaling.
For your convience, aliases matching the `object-fit` CSS property are provided, too. These are prefixed with css. Currently there is no equivalent for scale-down as it does not appear to be particularly useful here.