public static class BitmapFactory.Options extends Object
Modifier and Type | Field and Description |
---|---|
Bitmap |
inBitmap
If set, decode methods that take the Options object will attempt to
reuse this bitmap when loading content.
|
int |
inDensity
The pixel density to use for the bitmap.
|
boolean |
inDither
Deprecated.
As of
Build.VERSION_CODES.N , this is
ignored.
In Build.VERSION_CODES.M and below, if dither is
true, the decoder will attempt to dither the decoded image. |
boolean |
inInputShareable
Deprecated.
As of
Build.VERSION_CODES.LOLLIPOP , this is
ignored.
In Build.VERSION_CODES.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. |
boolean |
inJustDecodeBounds
If set to true, the decoder will return null (no bitmap), but
the out... fields will still be set, allowing the caller to query
the bitmap without having to allocate the memory for its pixels.
|
boolean |
inMutable
If set, decode methods will always return a mutable Bitmap instead of
an immutable one.
|
boolean |
inPreferQualityOverSpeed
Deprecated.
As of
Build.VERSION_CODES.N , this is
ignored. The output will always be high quality.
In Build.VERSION_CODES.M and below, 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. |
Bitmap.Config |
inPreferredConfig
If this is non-null, the decoder will try to decode into this
internal configuration.
|
boolean |
inPremultiplied
If true (which is the default), the resulting bitmap will have its
color channels pre-multipled by the alpha channel.
|
boolean |
inPurgeable
Deprecated.
As of
Build.VERSION_CODES.LOLLIPOP , this is
ignored.
In Build.VERSION_CODES.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 Note: This flag is ignored when used
with |
int |
inSampleSize
If set to a value > 1, requests the decoder to subsample the original
image, returning a smaller image to save memory.
|
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. |
int |
inScreenDensity
The pixel density of the actual screen that is being used.
|
int |
inTargetDensity
The pixel density of the destination this bitmap will be drawn to.
|
byte[] |
inTempStorage
Temp storage to use for decoding.
|
boolean |
mCancel
Deprecated.
As of
Build.VERSION_CODES.N , see
comments on requestCancelDecode() .
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. |
int |
outHeight
The resulting height of the bitmap.
|
String |
outMimeType
If known, this string is set to the mimetype of the decoded image.
|
int |
outWidth
The resulting width of the bitmap.
|
Constructor and Description |
---|
Options()
Create a default Options object, which if left unchanged will give
the same result from the decoder as if null were passed.
|
Modifier and Type | Method and Description |
---|---|
void |
requestCancelDecode()
Deprecated.
As of
Build.VERSION_CODES.N , this
will not affect the decode, though it will still set mCancel.
In Build.VERSION_CODES.M and below, if 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 |
public Bitmap inBitmap
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.
As of Build.VERSION_CODES.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 Build.VERSION_CODES.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.
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 Build.VERSION_CODES.JELLY_BEAN
. All
formats supported by BitmapRegionDecoder support Bitmap reuse via
inBitmap
.
public boolean inMutable
public boolean inJustDecodeBounds
public int inSampleSize
public Bitmap.Config inPreferredConfig
Bitmap.Config.ARGB_8888
config by
default.public boolean inPremultiplied
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.
Bitmap.hasAlpha()
,
Bitmap.isPremultiplied()
,
inScaled
public boolean inDither
Build.VERSION_CODES.N
, this is
ignored.
In Build.VERSION_CODES.M
and below, if dither is
true, the decoder will attempt to dither the decoded image.public int inDensity
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.
If this is 0,
BitmapFactory.decodeResource(Resources, int)
,
BitmapFactory.decodeResource(Resources, int, android.graphics.BitmapFactory.Options)
,
and BitmapFactory.decodeResourceStream(android.content.res.Resources, android.util.TypedValue, java.io.InputStream, android.graphics.Rect, android.graphics.BitmapFactory.Options)
will fill in the density associated with the resource. The other
functions will leave it as-is and no density will be applied.
public int inTargetDensity
inDensity
and
inScaled
to determine if and how to scale the bitmap before
returning it.
If this is 0,
BitmapFactory.decodeResource(Resources, int)
,
BitmapFactory.decodeResource(Resources, int, android.graphics.BitmapFactory.Options)
,
and BitmapFactory.decodeResourceStream(android.content.res.Resources, android.util.TypedValue, java.io.InputStream, android.graphics.Rect, android.graphics.BitmapFactory.Options)
will fill in the density associated the Resources object's
DisplayMetrics. The other
functions will leave it as-is and no scaling for density will be
performed.
inDensity
,
inScreenDensity
,
inScaled
,
DisplayMetrics.densityDpi
public int inScreenDensity
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.
inDensity
,
inTargetDensity
,
inScaled
,
DisplayMetrics.densityDpi
public boolean inScaled
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.
@Deprecated public boolean inPurgeable
Build.VERSION_CODES.LOLLIPOP
, this is
ignored.
In Build.VERSION_CODES.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.
Note: This flag is ignored when used
with BitmapFactory.decodeResource(Resources, int,
android.graphics.BitmapFactory.Options)
or BitmapFactory.decodeFile(String,
android.graphics.BitmapFactory.Options)
.
@Deprecated public boolean inInputShareable
Build.VERSION_CODES.LOLLIPOP
, this is
ignored.
In Build.VERSION_CODES.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
Build.VERSION_CODES.N
, this is
ignored. The output will always be high quality.
In Build.VERSION_CODES.M
and below, 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.public int outWidth
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.
outWidth will be set to -1 if there is an error trying to decode.
public int outHeight
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.
outHeight will be set to -1 if there is an error trying to decode.
public String outMimeType
public byte[] inTempStorage
public boolean mCancel
Build.VERSION_CODES.N
, see
comments on requestCancelDecode()
.
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 Options()
public void requestCancelDecode()
Build.VERSION_CODES.N
, this
will not affect the decode, though it will still set mCancel.
In Build.VERSION_CODES.M
and below, if 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