Package com.bumptech.glide.load.resource.bitmap

Class DownsampleStrategy

  • public abstract class DownsampleStrategy
extends java.lang.Object
    Indicates the algorithm to use when downsampling images.

    DownsampleStrategy does not provide any guarantees about output sizes. Behavior will differ depending on the ResourceDecoder using the strategy and the version of Android the code runs on. Use DownsampleStrategy as an optimization to improve memory efficiency only. If you need a particular size or shape output, use an Transformation either instead or in addition to a DownsampleStrategy.

    Some differences between versions of Android and ResourceDecoders are listed below, but the list is not comprehensive because DownsampleStrategy only controls its output scale value, not how that output value is used.

    On some versions of Android, precise scaling is not possible. In those cases, the strategies can only pick between downsampling to between 1x the requested size and 2x the requested size and between 0.5x the requested size and 1x the requested size because only power of two downsampling is supported. To preserve the potential for a Transformation to scale precisely without a loss in quality, all but AT_MOST will prefer to downsample to between 1x and 2x the requested size.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  DownsampleStrategy.SampleSizeRounding
      Indicates whether to prefer to prefer downsampling or scaling to prefer lower memory usage or higher quality.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static DownsampleStrategy AT_LEAST
      Downsamples so the image's smallest dimension is between the given dimensions and 2x the given dimensions, with no size restrictions on the image's largest dimension.
      static DownsampleStrategy AT_MOST
      Downsamples so the image's largest dimension is between 1/2 the given dimensions and the given dimensions, with no restrictions on the image's smallest dimension.
      static DownsampleStrategy CENTER_INSIDE
      Identical to FIT_CENTER, but never upscales.
      static DownsampleStrategy CENTER_OUTSIDE
      Scales, maintaining the original aspect ratio, so that one of the image's dimensions is exactly equal to the requested size and the other dimension is greater than or equal to the requested size.
      static DownsampleStrategy DEFAULT
      Default strategy, currently CENTER_OUTSIDE.
      static DownsampleStrategy FIT_CENTER
      Scales, maintaining the original aspect ratio, so that one of the image's dimensions is exactly equal to the requested size and the other dimension is less than or equal to the requested size.
      static DownsampleStrategy NONE
      Performs no downsampling or scaling.
      static Option<DownsampleStrategy> OPTION
      Indicates the DownsampleStrategy option that will be used to calculate the sample size to use to downsample an image given the original and target dimensions of the image.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      abstract DownsampleStrategy.SampleSizeRounding getSampleSizeRounding​(int sourceWidth, int sourceHeight, int requestedWidth, int requestedHeight)
      Returns a non-null DownsampleStrategy.SampleSizeRounding to use to resolve rounding errors and conflicts between scaling for the width and the height of the image.
      abstract float getScaleFactor​(int sourceWidth, int sourceHeight, int requestedWidth, int requestedHeight)
      Returns a float (0, +infinity) indicating a scale factor to apply to the source width and height when displayed in the requested width and height.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • AT_LEAST

        public static final DownsampleStrategy AT_LEAST
        Downsamples so the image's smallest dimension is between the given dimensions and 2x the given dimensions, with no size restrictions on the image's largest dimension.

        Does not upscale if the requested dimensions are larger than the original dimensions.

      • AT_MOST

        public static final DownsampleStrategy AT_MOST
        Downsamples so the image's largest dimension is between 1/2 the given dimensions and the given dimensions, with no restrictions on the image's smallest dimension.

        Does not upscale if the requested dimensions are larger than the original dimensions.

      • FIT_CENTER

        public static final DownsampleStrategy FIT_CENTER
        Scales, maintaining the original aspect ratio, so that one of the image's dimensions is exactly equal to the requested size and the other dimension is less than or equal to the requested size.

        This method will upscale if the requested width and height are greater than the source width and height. To avoid upscaling, use AT_LEAST, AT_MOST or CENTER_INSIDE.

        On pre-KitKat devices, FIT_CENTER will downsample by a power of two only so that one of the image's dimensions is greater than or equal to the requested size. No guarantees are made about the second dimensions. This is NOT the same as AT_LEAST because only one dimension, not both, are greater than or equal to the requested dimensions, the other may be smaller.

      • CENTER_OUTSIDE

        public static final DownsampleStrategy CENTER_OUTSIDE
        Scales, maintaining the original aspect ratio, so that one of the image's dimensions is exactly equal to the requested size and the other dimension is greater than or equal to the requested size.

        This method will upscale if the requested width and height are greater than the source width and height. To avoid upscaling, use AT_LEAST, AT_MOST, or CENTER_INSIDE.

        On pre-KitKat devices, Downsampler treats this as equivalent to AT_LEAST because only power of two downsampling can be used.

      • OPTION

        public static final Option<DownsampleStrategy> OPTION
        Indicates the DownsampleStrategy option that will be used to calculate the sample size to use to downsample an image given the original and target dimensions of the image.

    • Constructor Detail

      • DownsampleStrategy

        public DownsampleStrategy()

    • Method Detail

      • getScaleFactor

        public abstract float getScaleFactor​(int sourceWidth,
                                     int sourceHeight,
                                     int requestedWidth,
                                     int requestedHeight)
        Returns a float (0, +infinity) indicating a scale factor to apply to the source width and height when displayed in the requested width and height.

        The returned scale factor will be split into a power of two sample size applied via BitmapFactory.Options.inSampleSize and a float scale factor applied after downsampling via BitmapFactory.Options.inTargetDensity and BitmapFactory.Options.inDensity. Because of rounding errors the scale factor may not be applied precisely.

        The float scaling factor will only be applied on KitKat+. Prior to KitKat, only the power of two downsampling will be applied.

        Parameters:
        sourceWidth - The width in pixels of the image to be downsampled.
        sourceHeight - The height in pixels of the image to be downsampled.
        requestedWidth - The width in pixels of the view/target the image will be displayed in.
        requestedHeight - The height in pixels of the view/target the image will be displayed in.

      • getSampleSizeRounding

        public abstract DownsampleStrategy.SampleSizeRounding getSampleSizeRounding​(int sourceWidth,
                                                                            int sourceHeight,
                                                                            int requestedWidth,
                                                                            int requestedHeight)
        Returns a non-null DownsampleStrategy.SampleSizeRounding to use to resolve rounding errors and conflicts between scaling for the width and the height of the image.
        Parameters:
        sourceWidth - The width in pixels of the image to be downsampled.
        sourceHeight - The height in pixels of the image to be downsampled.
        requestedWidth - The width in pixels of the view/target the image will be displayed in.
        requestedHeight - The height in pixels of the view/target the image will be displayed in.