This field was deprecated
in API level 21.
As of LOLLIPOP, this is
ignored.
In KITKAT and below, this
field works in conjuction with inPurgeable. If inPurgeable is false,
then this field is ignored. If inPurgeable is true, then this field
determines whether the bitmap can share a reference to the input
data (inputstream, array, etc.) or if it must make a deep copy.

This field was deprecated
in API level 21.
As of LOLLIPOP, this is
ignored.
In KITKAT and below, if this
is set to true, then the resulting bitmap will allocate its
pixels such that they can be purged if the system needs to reclaim
memory. In that instance, when the pixels need to be accessed again
(e.g. the bitmap is drawn, getPixels() is called), they will be
automatically re-decoded.

For the re-decode to happen, the bitmap must have access to the
encoded data, either by sharing a reference to the input
or by making a copy of it. This distinction is controlled by
inInputShareable. If this is true, then the bitmap may keep a shallow
reference to the input. If this is false, then the bitmap will
explicitly make a copy of the input data, and keep that. Even if
sharing is allowed, the implementation may still decide to make a
deep copy of the input data.

While inPurgeable can help avoid big Dalvik heap allocations (from
API level 11 onward), it sacrifices performance predictability since any
image that the view system tries to draw may incur a decode delay which
can lead to dropped frames. Therefore, most apps should avoid using
inPurgeable to allow for a fast and fluid UI. To minimize Dalvik heap
allocations use the inBitmap flag instead.

When this flag is set, if inDensity and
inTargetDensity are not 0, the
bitmap will be scaled to match inTargetDensity when loaded,
rather than relying on the graphics system scaling it each time it
is drawn to a Canvas.

Fields

If set, decode methods that take the Options object will attempt to
reuse this bitmap when loading content. If the decode operation
cannot use this bitmap, the decode method will return
null and will throw an IllegalArgumentException. The
current implementation necessitates that the reused bitmap be
mutable, and the resulting reused bitmap will continue to remain
mutable even when decoding a resource which would normally result in
an immutable bitmap.

You should still always use the returned Bitmap of the decode
method and not assume that reusing the bitmap worked, due to the
constraints outlined above and failure situations that can occur.
Checking whether the return value matches the value of the inBitmap
set in the Options structure will indicate if the bitmap was reused,
but in all cases you should use the Bitmap returned by the decoding
function to ensure that you are using the bitmap that was used as the
decode destination.

Usage with BitmapFactory

As of KITKAT, any
mutable bitmap can be reused by BitmapFactory to decode any
other bitmaps as long as the resulting byte count of the decoded bitmap is less than or equal to the allocated byte count of the reused
bitmap. This can be because the intrinsic size is smaller, or its
size post scaling (for density / sample size) is smaller.

Prior to KITKAT
additional constraints apply: The image being decoded (whether as a
resource or as a stream) must be in jpeg or png format. Only equal
sized bitmaps are supported, with inSampleSize set to 1.
Additionally, the configuration of the reused bitmap will override the setting of
inPreferredConfig, if set.

Usage with BitmapRegionDecoder

BitmapRegionDecoder will draw its requested content into the Bitmap
provided, clipping if the output content size (post scaling) is larger
than the provided Bitmap. The provided Bitmap's width, height, and
Bitmap.Config will not be changed.

BitmapRegionDecoder support for inBitmap was
introduced in JELLY_BEAN. All
formats supported by BitmapRegionDecoder support Bitmap reuse via
inBitmap.

See Also

public
int
inDensity

The pixel density to use for the bitmap. This will always result
in the returned bitmap having a density set for it (see
Bitmap.setDensity(int)). In addition,
if inScaled is set (which it is by default} and this
density does not match inTargetDensity, then the bitmap
will be scaled to the target density before being returned.

public
boolean
inDither

public
boolean
inInputShareable

This field was deprecated
in API level 21.
As of LOLLIPOP, this is
ignored.
In KITKAT and below, this
field works in conjuction with inPurgeable. If inPurgeable is false,
then this field is ignored. If inPurgeable is true, then this field
determines whether the bitmap can share a reference to the input
data (inputstream, array, etc.) or if it must make a deep copy.

public
boolean
inPreferQualityOverSpeed

If inPreferQualityOverSpeed is set to true, the decoder will try to
decode the reconstructed image to a higher quality even at the
expense of the decoding speed. Currently the field only affects JPEG
decode, in the case of which a more accurate, but slightly slower,
IDCT method will be used instead.

If this is non-null, the decoder will try to decode into this
internal configuration. If it is null, or the request cannot be met,
the decoder will try to pick the best matching config based on the
system's screen depth, and characteristics of the original image such
as if it has per-pixel alpha (requiring a config that also does).
Image are loaded with the ARGB_8888 config by
default.

public
boolean
inPremultiplied

If true (which is the default), the resulting bitmap will have its
color channels pre-multipled by the alpha channel.

This should NOT be set to false for images to be directly drawn by
the view system or through a Canvas. The view system and
Canvas assume all drawn images are pre-multiplied to simplify
draw-time blending, and will throw a RuntimeException when
un-premultiplied are drawn.

This is likely only useful if you want to manipulate raw encoded
image data, e.g. with RenderScript or custom OpenGL.

This does not affect bitmaps without an alpha channel.

Setting this flag to false while setting inScaled to true
may result in incorrect colors.

See Also

public
boolean
inPurgeable

This field was deprecated
in API level 21.
As of LOLLIPOP, this is
ignored.
In KITKAT and below, if this
is set to true, then the resulting bitmap will allocate its
pixels such that they can be purged if the system needs to reclaim
memory. In that instance, when the pixels need to be accessed again
(e.g. the bitmap is drawn, getPixels() is called), they will be
automatically re-decoded.

For the re-decode to happen, the bitmap must have access to the
encoded data, either by sharing a reference to the input
or by making a copy of it. This distinction is controlled by
inInputShareable. If this is true, then the bitmap may keep a shallow
reference to the input. If this is false, then the bitmap will
explicitly make a copy of the input data, and keep that. Even if
sharing is allowed, the implementation may still decide to make a
deep copy of the input data.

While inPurgeable can help avoid big Dalvik heap allocations (from
API level 11 onward), it sacrifices performance predictability since any
image that the view system tries to draw may incur a decode delay which
can lead to dropped frames. Therefore, most apps should avoid using
inPurgeable to allow for a fast and fluid UI. To minimize Dalvik heap
allocations use the inBitmap flag instead.

public
int
inSampleSize

If set to a value > 1, requests the decoder to subsample the original
image, returning a smaller image to save memory. The sample size is
the number of pixels in either dimension that correspond to a single
pixel in the decoded bitmap. For example, inSampleSize == 4 returns
an image that is 1/4 the width/height of the original, and 1/16 the
number of pixels. Any value <= 1 is treated the same as 1. Note: the
decoder uses a final value based on powers of 2, any other value will
be rounded down to the nearest power of 2.

public
boolean
inScaled

When this flag is set, if inDensity and
inTargetDensity are not 0, the
bitmap will be scaled to match inTargetDensity when loaded,
rather than relying on the graphics system scaling it each time it
is drawn to a Canvas.

BitmapRegionDecoder ignores this flag, and will not scale output
based on density. (though inSampleSize is supported)

This flag is turned on by default and should be turned off if you need
a non-scaled version of the bitmap. Nine-patch bitmaps ignore this
flag and are always scaled.

If inPremultiplied is set to false, and the image has alpha,
setting this flag to true may result in incorrect colors.

public
int
inScreenDensity

The pixel density of the actual screen that is being used. This is
purely for applications running in density compatibility code, where
inTargetDensity is actually the density the application
sees rather than the real screen density.

By setting this, you
allow the loading code to avoid scaling a bitmap that is currently
in the screen density up/down to the compatibility density. Instead,
if inDensity is the same as inScreenDensity, the
bitmap will be left as-is. Anything using the resulting bitmap
must also used Bitmap.getScaledWidth and Bitmap.getScaledHeight to account for any different between the
bitmap's density and the target's density.

This is never set automatically for the caller by
BitmapFactory itself. It must be explicitly set, since the
caller must deal with the resulting bitmap in a density-aware way.

See Also

public
byte[]
inTempStorage

public
boolean
mCancel

Flag to indicate that cancel has been called on this object. This
is useful if there's an intermediary that wants to first decode the
bounds and then decode the image. In that case the intermediary
can check, inbetween the bounds decode and the image decode, to see
if the operation is canceled.

public
int
outHeight

The resulting height of the bitmap. If inJustDecodeBounds is
set to false, this will be height of the output bitmap after any
scaling is applied. If true, it will be the height of the input image
without any accounting for scaling.

public
int
outWidth

The resulting width of the bitmap. If inJustDecodeBounds is
set to false, this will be width of the output bitmap after any
scaling is applied. If true, it will be the width of the input image
without any accounting for scaling.

Public Methods

public
void
requestCancelDecode()

This can be called from another thread while this options object is
inside a decode... call. Calling this will notify the decoder that
it should cancel its operation. This is not guaranteed to cancel
the decode, but if it does, the decoder... operation will return
null, or if inJustDecodeBounds is true, will set outWidth/outHeight
to -1