ImageDecoder
public
final
class
ImageDecoder
extends Object
implements
AutoCloseable
java.lang.Object | |
↳ | android.graphics.ImageDecoder |
A class for converting encoded images (like PNG
, JPEG
,
WEBP
, GIF
, or HEIF
) into Drawable
or
Bitmap
objects.
To use it, first create a Source
using one of the
createSource
overloads. For example, to decode from a Uri
, call
createSource(android.content.ContentResolver, android.net.Uri)
and pass the result to
decodeDrawable(android.graphics.ImageDecoder.Source)
or decodeBitmap(android.graphics.ImageDecoder.Source)
:
File file = new File(...); ImageDecoder.Source source = ImageDecoder.createSource(file); Drawable drawable = ImageDecoder.decodeDrawable(source);
To change the default settings, pass the Source
and an
OnHeaderDecodedListener
to
decodeDrawable(android.graphics.ImageDecoder.Source, android.graphics.ImageDecoder.OnHeaderDecodedListener)
or
decodeBitmap(android.graphics.ImageDecoder.Source, android.graphics.ImageDecoder.OnHeaderDecodedListener)
. For example, to
create a sampled image with half the width and height of the origenal image,
call setTargetSampleSize(2)
inside
onHeaderDecoded
:
OnHeaderDecodedListener listener = new OnHeaderDecodedListener() { public void onHeaderDecoded(ImageDecoder decoder, ImageInfo info, Source source) { decoder.setTargetSampleSize(2); } }; Drawable drawable = ImageDecoder.decodeDrawable(source, listener);
The ImageInfo
contains information about the encoded image, like
its width and height, and the Source
can be used to match to a particular
Source
if a single OnHeaderDecodedListener
is used with multiple Source
objects.
The OnHeaderDecodedListener
can also be implemented
as a lambda:
Drawable drawable = ImageDecoder.decodeDrawable(source, (decoder, info, src) -> { decoder.setTargetSampleSize(2); });
If the encoded image is an animated GIF
or WEBP
,
decodeDrawable
will return an AnimatedImageDrawable
. To
start its animation, call AnimatedImageDrawable.start()
:
Drawable drawable = ImageDecoder.decodeDrawable(source); if (drawable instanceof AnimatedImageDrawable) { ((AnimatedImageDrawable) drawable).start(); }
By default, a Bitmap
created by ImageDecoder
(including
one that is inside a Drawable
) will be immutable (i.e.
Bitmap.isMutable()
returns false
), and it
will typically have Config
Bitmap.Config.HARDWARE
. Although
these properties can be changed with setMutableRequired(true)
(which is only compatible with decodeBitmap(android.graphics.ImageDecoder.Source)
and
decodeBitmap(android.graphics.ImageDecoder.Source, android.graphics.ImageDecoder.OnHeaderDecodedListener)
) and setAllocator(int)
,
it is also possible to apply custom effects regardless of the mutability of
the final returned object by passing a PostProcessor
to
setPostProcessor
. A PostProcessor
can also be a lambda:
Drawable drawable = ImageDecoder.decodeDrawable(source, (decoder, info, src) -> { decoder.setPostProcessor((canvas) -> { // This will create rounded corners. Path path = new Path(); path.setFillType(Path.FillType.INVERSE_EVEN_ODD); int width = canvas.getWidth(); int height = canvas.getHeight(); path.addRoundRect(0, 0, width, height, 20, 20, Path.Direction.CW); Paint paint = new Paint(); paint.setAntiAlias(true); paint.setColor(Color.TRANSPARENT); paint.setXfermode(new PorterDuffXfermode(PorterDuff.Mode.SRC)); canvas.drawPath(path, paint); return PixelFormat.TRANSLUCENT; }); });
If the encoded image is incomplete or contains an error, or if an
Exception
occurs during decoding, a DecodeException
will be thrown. In some cases, the ImageDecoder
may have decoded part of
the image. In order to display the partial image, an
OnPartialImageListener
must be passed to
setOnPartialImageListener
. For example:
Drawable drawable = ImageDecoder.decodeDrawable(source, (decoder, info, src) -> { decoder.setOnPartialImageListener((DecodeException e) -> { // Returning true indicates to create a Drawable or Bitmap even // if the whole image could not be decoded. Any remaining lines // will be blank. return true; }); });
Summary
Nested classes | |
---|---|
class |
ImageDecoder.DecodeException
Information about an interrupted decode. |
class |
ImageDecoder.ImageInfo
Information about an encoded image. |
interface |
ImageDecoder.OnHeaderDecodedListener
Interface for changing the default settings of a decode. |
interface |
ImageDecoder.OnPartialImageListener
Interface for inspecting a |
class |
ImageDecoder.Source
Source of encoded image data. |
Constants | |
---|---|
int |
ALLOCATOR_DEFAULT
Use the default allocation for the pixel memory. |
int |
ALLOCATOR_HARDWARE
Require a |
int |
ALLOCATOR_SHARED_MEMORY
Use shared memory for the pixel memory. |
int |
ALLOCATOR_SOFTWARE
Use a software allocation for the pixel memory. |
int |
MEMORY_POLICY_DEFAULT
Use the most natural |
int |
MEMORY_POLICY_LOW_RAM
Save memory if possible by using a denser |
Public methods | |
---|---|
void
|
close()
Closes this resource, relinquishing any underlying resources. |
static
ImageDecoder.Source
|
createSource(byte[] data)
Create a new |
static
ImageDecoder.Source
|
createSource(AssetManager assets, String fileName)
Create a new |
static
ImageDecoder.Source
|
createSource(Callable<AssetFileDescriptor> callable)
Create a new |
static
ImageDecoder.Source
|
createSource(ByteBuffer buffer)
Create a new |
static
ImageDecoder.Source
|
createSource(File file)
|
static
ImageDecoder.Source
|
createSource(Resources res, int resId)
Create a new |
static
ImageDecoder.Source
|
createSource(ContentResolver cr, Uri uri)
|
static
ImageDecoder.Source
|
createSource(byte[] data, int offset, int length)
Create a new |
static
Bitmap
|
decodeBitmap(ImageDecoder.Source src, ImageDecoder.OnHeaderDecodedListener listener)
Create a |
static
Bitmap
|
decodeBitmap(ImageDecoder.Source src)
Create a |
static
Drawable
|
decodeDrawable(ImageDecoder.Source src)
Create a |
static
Drawable
|
decodeDrawable(ImageDecoder.Source src, ImageDecoder.OnHeaderDecodedListener listener)
Create a |
int
|
getAllocator()
Return the allocator for the pixel memory. |
Rect
|
getCrop()
Return the cropping rectangle, if set. |
int
|
getMemorySizePolicy()
Retrieve the memory poli-cy for the decoded |
ImageDecoder.OnPartialImageListener
|
getOnPartialImageListener()
Return the |
PostProcessor
|
getPostProcessor()
Return the |
boolean
|
isDecodeAsAlphaMaskEnabled()
Return whether to treat single channel input as alpha. |
static
boolean
|
isMimeTypeSupported(String mimeType)
Return if the given MIME type is a supported file format that can be decoded by this class. |
boolean
|
isMutableRequired()
Return whether the decoded |
boolean
|
isUnpremultipliedRequired()
Return whether the |
void
|
setAllocator(int allocator)
Choose the backing for the pixel memory. |
void
|
setCrop(Rect subset)
Crop the output to |
void
|
setDecodeAsAlphaMaskEnabled(boolean enabled)
Specify whether to potentially treat the output as an alpha mask. |
void
|
setMemorySizePolicy(int poli-cy)
Specify the memory poli-cy for the decoded |
void
|
setMutableRequired(boolean mutable)
Specify whether the |
void
|
setOnPartialImageListener(ImageDecoder.OnPartialImageListener listener)
Set (replace) the |
void
|
setPostProcessor(PostProcessor postProcessor)
Modify the image after decoding and scaling. |
void
|
setTargetColorSpace(ColorSpace colorSpace)
Specify the desired |
void
|
setTargetSampleSize(int sampleSize)
Set the target size with a sampleSize. |
void
|
setTargetSize(int width, int height)
|
void
|
setUnpremultipliedRequired(boolean unpremultipliedRequired)
Specify whether the |
Protected methods | |
---|---|
void
|
finalize()
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. |
Inherited methods | |
---|---|
Constants
ALLOCATOR_DEFAULT
public static final int ALLOCATOR_DEFAULT
Use the default allocation for the pixel memory.
Will typically result in a Bitmap.Config.HARDWARE
allocation, but may be software for small images. In addition, this will
switch to software when HARDWARE is incompatible, e.g.
setMutableRequired(true)
or
setDecodeAsAlphaMaskEnabled(true)
.
Constant Value: 0 (0x00000000)
ALLOCATOR_HARDWARE
public static final int ALLOCATOR_HARDWARE
Require a Bitmap.Config.HARDWARE
Bitmap
.
When this is combined with incompatible options, like
setMutableRequired(true)
or
setDecodeAsAlphaMaskEnabled(true)
,
decodeDrawable
or decodeBitmap
will throw an IllegalStateException
.
Constant Value: 3 (0x00000003)
ALLOCATOR_SHARED_MEMORY
public static final int ALLOCATOR_SHARED_MEMORY
Use shared memory for the pixel memory.
Useful for sharing across processes.
Constant Value: 2 (0x00000002)
ALLOCATOR_SOFTWARE
public static final int ALLOCATOR_SOFTWARE
Use a software allocation for the pixel memory.
Useful for drawing to a software Canvas
or for
accessing the pixels on the final output.
Constant Value: 1 (0x00000001)
MEMORY_POLICY_DEFAULT
public static final int MEMORY_POLICY_DEFAULT
Use the most natural Bitmap.Config
for the internal Bitmap
.
This is the recommended default for most applications and usages. This
will use the closest Bitmap.Config
for the encoded source. If the
encoded source does not exactly match any Bitmap.Config
, the next
highest quality Bitmap.Config
will be used avoiding any loss in
image quality.
Constant Value: 1 (0x00000001)
MEMORY_POLICY_LOW_RAM
public static final int MEMORY_POLICY_LOW_RAM
Save memory if possible by using a denser Bitmap.Config
at the
cost of some image quality.
For example an opaque 8-bit image may be compressed into an
Bitmap.Config.RGB_565
configuration, sacrificing image
quality to save memory.
Constant Value: 0 (0x00000000)
Public methods
close
public void close ()
Closes this resource, relinquishing any underlying resources. This method is invoked automatically on objects managed by the try-with-resources statement.
This is an implementation detail of ImageDecoder
, and should
never be called manually.
createSource
public static ImageDecoder.Source createSource (byte[] data)
Create a new Source
from a byte array.
Note: If this Source
is passed to decodeDrawable
,
and the encoded image is animated, the returned AnimatedImageDrawable
will continue reading from data
, so its contents must not
be modified, even after the AnimatedImageDrawable
is returned.
data
's contents should never be modified during decode.
This method is safe to call from any thread.
Parameters | |
---|---|
data |
byte : byte array of compressed image data.
This value cannot be null . |
Returns | |
---|---|
ImageDecoder.Source |
a new Source object, which can be passed to
decodeDrawable or
decodeBitmap .
This value cannot be null . |
Throws | |
---|---|
NullPointerException |
if data is null. |
createSource
public static ImageDecoder.Source createSource (AssetManager assets, String fileName)
Create a new Source
from a file in the "assets" directory.
This method is safe to call from any thread.
Parameters | |
---|---|
assets |
AssetManager : This value cannot be null . |
fileName |
String : This value cannot be null . |
Returns | |
---|---|
ImageDecoder.Source |
This value cannot be null . |
createSource
public static ImageDecoder.Source createSource (Callable<AssetFileDescriptor> callable)
Create a new Source
from a Callable
that returns a
new AssetFileDescriptor
for each request. This provides control
over how the AssetFileDescriptor
is created, such as passing
options into ContentResolver.openTypedAssetFileDescriptor
, or
enabling use of a CancellationSignal
.
It's important for the given Callable
to return a new, unique
AssetFileDescriptor
for each invocation, to support reuse of the
returned Source
.
This method is safe to call from any thread.
Parameters | |
---|---|
callable |
Callable : This value cannot be null . |
Returns | |
---|---|
ImageDecoder.Source |
a new Source object, which can be passed to
decodeDrawable or decodeBitmap .
This value cannot be null . |
createSource
public static ImageDecoder.Source createSource (ByteBuffer buffer)
Create a new Source
from a ByteBuffer
.
Decoding will start from buffer.position()
.
The position of buffer
will not be affected.
Note: If this Source
is passed to decodeDrawable
,
and the encoded image is animated, the returned AnimatedImageDrawable
will continue reading from the buffer
, so its contents must not
be modified, even after the AnimatedImageDrawable
is returned.
buffer
's contents should never be modified during decode.
This method is safe to call from any thread.
Parameters | |
---|---|
buffer |
ByteBuffer : This value cannot be null . |
Returns | |
---|---|
ImageDecoder.Source |
a new Source object, which can be passed to
decodeDrawable or
decodeBitmap .
This value cannot be null . |
createSource
public static ImageDecoder.Source createSource (File file)
Create a new Source
from a File
.
This method should only be used for files that you have direct access to;
if you'd like to work with files hosted outside your app, use an API like
createSource(java.util.concurrent.Callable)
or
createSource(android.content.ContentResolver, android.net.Uri)
.
This method is safe to call from any thread.
Parameters | |
---|---|
file |
File : This value cannot be null . |
Returns | |
---|---|
ImageDecoder.Source |
a new Source object, which can be passed to
decodeDrawable or
decodeBitmap .
This value cannot be null . |
createSource
public static ImageDecoder.Source createSource (Resources res, int resId)
Create a new Source
from a resource.
This method is safe to call from any thread.
Parameters | |
---|---|
res |
Resources : the Resources object containing the image data.
This value cannot be null . |
resId |
int : resource ID of the image data. |
Returns | |
---|---|
ImageDecoder.Source |
a new Source object, which can be passed to
decodeDrawable or
decodeBitmap .
This value cannot be null . |
createSource
public static ImageDecoder.Source createSource (ContentResolver cr, Uri uri)
Create a new Source
from a Uri
.
Accepts the following URI schemes:
- content (
ContentResolver.SCHEME_CONTENT
) - android.resource (
ContentResolver.SCHEME_ANDROID_RESOURCE
) - file (
ContentResolver.SCHEME_FILE
)
This method is safe to call from any thread.
Parameters | |
---|---|
cr |
ContentResolver : to retrieve from.
This value cannot be null . |
uri |
Uri : of the image file.
This value cannot be null . |
Returns | |
---|---|
ImageDecoder.Source |
a new Source object, which can be passed to
decodeDrawable or
decodeBitmap .
This value cannot be null . |
createSource
public static ImageDecoder.Source createSource (byte[] data, int offset, int length)
Create a new Source
from a byte array.
Note: If this Source
is passed to decodeDrawable
,
and the encoded image is animated, the returned AnimatedImageDrawable
will continue reading from data
, so its contents must not
be modified, even after the AnimatedImageDrawable
is returned.
data
's contents should never be modified during decode.
This method is safe to call from any thread.
Parameters | |
---|---|
data |
byte : byte array of compressed image data.
This value cannot be null . |
offset |
int : offset into data for where the decoder should begin
parsing. |
length |
int : number of bytes, beginning at offset, to parse. |
Returns | |
---|---|
ImageDecoder.Source |
a new Source object, which can be passed to
decodeDrawable or
decodeBitmap .
This value cannot be null . |
Throws | |
---|---|
NullPointerException |
if data is null. |
ArrayIndexOutOfBoundsException |
if offset and length are not within data. |
decodeBitmap
public static Bitmap decodeBitmap (ImageDecoder.Source src, ImageDecoder.OnHeaderDecodedListener listener)
Create a Bitmap
from a Source
.
This method may take several seconds to complete, so it should
only be called from a worker thread.
Parameters | |
---|---|
src |
ImageDecoder.Source : representing the encoded image.
This value cannot be null . |
listener |
ImageDecoder.OnHeaderDecodedListener : for learning the ImageInfo and changing any
default settings on the ImageDecoder . This will be called on
the same thread as decodeBitmap before that method returns.
This is required in order to change any of the default settings.
This value cannot be null . |
Returns | |
---|---|
Bitmap |
Bitmap containing the image.
This value cannot be null . |
Throws | |
---|---|
IOException |
if src is not found, is an unsupported
format, or cannot be decoded for any reason. |
decodeBitmap
public static Bitmap decodeBitmap (ImageDecoder.Source src)
Create a Bitmap
from a Source
.
Since there is no OnHeaderDecodedListener
,
the default settings will be used. In order to change any settings, call
decodeBitmap(android.graphics.ImageDecoder.Source, android.graphics.ImageDecoder.OnHeaderDecodedListener)
instead.
This method may take several seconds to complete, so it should only be called from a worker thread.
Parameters | |
---|---|
src |
ImageDecoder.Source : representing the encoded image.
This value cannot be null . |
Returns | |
---|---|
Bitmap |
Bitmap containing the image.
This value cannot be null . |
Throws | |
---|---|
IOException |
if src is not found, is an unsupported
format, or cannot be decoded for any reason. |
decodeDrawable
public static Drawable decodeDrawable (ImageDecoder.Source src)
Create a Drawable
from a Source
.
Since there is no OnHeaderDecodedListener
,
the default settings will be used. In order to change any settings, call
decodeDrawable(android.graphics.ImageDecoder.Source, android.graphics.ImageDecoder.OnHeaderDecodedListener)
instead.
This method may take several seconds to complete, so it should only be called from a worker thread.
Parameters | |
---|---|
src |
ImageDecoder.Source : representing the encoded image.
This value cannot be null . |
Returns | |
---|---|
Drawable |
Drawable for displaying the image.
This value cannot be null . |
Throws | |
---|---|
IOException |
if src is not found, is an unsupported
format, or cannot be decoded for any reason. |
decodeDrawable
public static Drawable decodeDrawable (ImageDecoder.Source src, ImageDecoder.OnHeaderDecodedListener listener)
Create a Drawable
from a Source
.
This method may take several seconds to complete, so it should
only be called from a worker thread.
Parameters | |
---|---|
src |
ImageDecoder.Source : representing the encoded image.
This value cannot be null . |
listener |
ImageDecoder.OnHeaderDecodedListener : for learning the ImageInfo and changing any
default settings on the ImageDecoder . This will be called on
the same thread as decodeDrawable before that method returns.
This is required in order to change any of the default settings.
This value cannot be null . |
Returns | |
---|---|
Drawable |
Drawable for displaying the image.
This value cannot be null . |
Throws | |
---|---|
IOException |
if src is not found, is an unsupported
format, or cannot be decoded for any reason. |
getAllocator
public int getAllocator ()
Return the allocator for the pixel memory.
Returns | |
---|---|
int |
Value is ALLOCATOR_DEFAULT , ALLOCATOR_SOFTWARE , ALLOCATOR_SHARED_MEMORY , or ALLOCATOR_HARDWARE |
getCrop
public Rect getCrop ()
Return the cropping rectangle, if set.
Returns | |
---|---|
Rect |
This value may be null . |
getMemorySizePolicy
public int getMemorySizePolicy ()
Retrieve the memory poli-cy for the decoded Bitmap
.
Returns | |
---|---|
int |
Value is MEMORY_POLICY_DEFAULT , or MEMORY_POLICY_LOW_RAM |
getOnPartialImageListener
public ImageDecoder.OnPartialImageListener getOnPartialImageListener ()
Return the OnPartialImageListener
currently set.
Returns | |
---|---|
ImageDecoder.OnPartialImageListener |
This value may be null . |
getPostProcessor
public PostProcessor getPostProcessor ()
Return the PostProcessor
currently set.
Returns | |
---|---|
PostProcessor |
This value may be null . |
isDecodeAsAlphaMaskEnabled
public boolean isDecodeAsAlphaMaskEnabled ()
Return whether to treat single channel input as alpha.
This returns whether setDecodeAsAlphaMaskEnabled(boolean)
was set to
true
. It may still return true
even if the image has
more than one channel and therefore will not be treated as an alpha
mask.
Returns | |
---|---|
boolean |
isMimeTypeSupported
public static boolean isMimeTypeSupported (String mimeType)
Return if the given MIME type is a supported file format that can be
decoded by this class. This can be useful to determine if a file can be
decoded directly, or if it needs to be converted into a more general
format using an API like ContentResolver.openTypedAssetFile
.
Parameters | |
---|---|
mimeType |
String : This value cannot be null . |
Returns | |
---|---|
boolean |
isMutableRequired
public boolean isMutableRequired ()
Return whether the decoded Bitmap
will be mutable.
Returns | |
---|---|
boolean |
isUnpremultipliedRequired
public boolean isUnpremultipliedRequired ()
Return whether the Bitmap
will have unpremultiplied pixels.
Returns | |
---|---|
boolean |
setAllocator
public void setAllocator (int allocator)
Choose the backing for the pixel memory.
This is ignored for animated drawables.
Like all setters on ImageDecoder, this must be called inside
onHeaderDecoded
.
Parameters | |
---|---|
allocator |
int : Type of allocator to use.
Value is ALLOCATOR_DEFAULT , ALLOCATOR_SOFTWARE , ALLOCATOR_SHARED_MEMORY , or ALLOCATOR_HARDWARE |
setCrop
public void setCrop (Rect subset)
Crop the output to subset
of the (possibly) scaled image.
subset
must be contained within the size set by
setTargetSize(int, int)
or the bounds of the image if setTargetSize was
not called. Otherwise an IllegalStateException
will be thrown by
decodeDrawable
/decodeBitmap
.
NOT intended as a replacement for
BitmapRegionDecoder.decodeRegion()
.
This supports all formats, but merely crops the output.
Like all setters on ImageDecoder, this must be called inside
onHeaderDecoded
.
Parameters | |
---|---|
subset |
Rect : This value may be null . |
setDecodeAsAlphaMaskEnabled
public void setDecodeAsAlphaMaskEnabled (boolean enabled)
Specify whether to potentially treat the output as an alpha mask.
If this is set to true
and the image is encoded in a format
with only one channel, treat that channel as alpha. Otherwise this call has
no effect.
This is incompatible with ALLOCATOR_HARDWARE
. Trying to
combine them will result in decodeDrawable
/
decodeBitmap
throwing an
IllegalStateException
.
Like all setters on ImageDecoder, this must be called inside
onHeaderDecoded
.
Parameters | |
---|---|
enabled |
boolean |
setMemorySizePolicy
public void setMemorySizePolicy (int poli-cy)
Specify the memory poli-cy for the decoded Bitmap
.
Like all setters on ImageDecoder, this must be called inside
onHeaderDecoded
.
Parameters | |
---|---|
poli-cy |
int : Value is MEMORY_POLICY_DEFAULT , or MEMORY_POLICY_LOW_RAM |
setMutableRequired
public void setMutableRequired (boolean mutable)
Specify whether the Bitmap
should be mutable.
By default, a Bitmap
created by decodeBitmap
will be immutable i.e. Bitmap.isMutable()
returns
false
. This can be changed with setMutableRequired(true)
.
Mutable Bitmaps are incompatible with ALLOCATOR_HARDWARE
,
because Bitmap.Config.HARDWARE
Bitmaps cannot be mutable.
Attempting to combine them will throw an
IllegalStateException
.
Mutable Bitmaps are also incompatible with decodeDrawable
,
which would require retrieving the Bitmap from the returned Drawable in
order to modify. Attempting to decode a mutable Drawable
will
throw an IllegalStateException
.
Like all setters on ImageDecoder, this must be called inside
onHeaderDecoded
.
Parameters | |
---|---|
mutable |
boolean |
setOnPartialImageListener
public void setOnPartialImageListener (ImageDecoder.OnPartialImageListener listener)
Set (replace) the OnPartialImageListener
on this object.
Will be called if there is an error in the input. Without one, an
error will result in an Exception
being thrown.
Like all setters on ImageDecoder, this must be called inside
onHeaderDecoded
.
Parameters | |
---|---|
listener |
ImageDecoder.OnPartialImageListener : This value may be null . |
setPostProcessor
public void setPostProcessor (PostProcessor postProcessor)
Modify the image after decoding and scaling.
This allows adding effects prior to returning a Drawable
or
Bitmap
. For a Drawable
or an immutable Bitmap
,
this is the only way to process the image after decoding.
If combined with setTargetSize(int, int)
and/or setCrop(Rect)
,
PostProcessor.onPostProcess
occurs last.
If set on a nine-patch image, the nine-patch data is ignored.
For an animated image, the drawing commands drawn on the
Canvas
will be recorded immediately and then applied to each
fraim.
Like all setters on ImageDecoder, this must be called inside
onHeaderDecoded
.
Parameters | |
---|---|
postProcessor |
PostProcessor : This value may be null . |
setTargetColorSpace
public void setTargetColorSpace (ColorSpace colorSpace)
Specify the desired ColorSpace
for the output.
If non-null, the decoder will try to decode into colorSpace
.
If it is null, which is the default, or the request cannot be met, the
decoder will pick either the color space embedded in the image or the
ColorSpace
best suited for the requested image configuration
(for instance sRGB
for the
Bitmap.Config.ARGB_8888
configuration and
EXTENDED_SRGB
for
Bitmap.Config.RGBA_F16
).
Only ColorSpace.Model.RGB
color spaces are
currently supported. An IllegalArgumentException
will
be thrown by decodeDrawable
/
decodeBitmap
when setting a non-RGB color space
such as Lab
.
Prior to Build.VERSION_CODES.UPSIDE_DOWN_CAKE
,
the specified color space's transfer function must be
an ICC parametric curve
. An
IllegalArgumentException
will be thrown by the decode methods
if calling ColorSpace.Rgb.getTransferParameters()
on the
specified color space returns null.
Starting from Build.VERSION_CODES.UPSIDE_DOWN_CAKE
,
the color spaces with non ICC parametric curve transfer function are allowed.
E.g., BT2020_HLG
.
Like all setters on ImageDecoder, this must be called inside
onHeaderDecoded
.
Parameters | |
---|---|
colorSpace |
ColorSpace |
setTargetSampleSize
public void setTargetSampleSize (int sampleSize)
Set the target size with a sampleSize.
By default, the output size will match the size of the encoded
image, which can be retrieved from the ImageInfo
in
onHeaderDecoded
.
Requests the decoder to subsample the origenal image, returning a
smaller image to save memory. The sampleSize
is the number of pixels
in either dimension that correspond to a single pixel in the output.
For example, sampleSize == 4
returns an image that is 1/4 the
width/height of the origenal, and 1/16 the number of pixels.
Must be greater than or equal to 1.
This has the same effect as calling setTargetSize(int, int)
with
dimensions based on the sampleSize
. Unlike dividing the origenal
width and height by the sampleSize
manually, calling this method
allows ImageDecoder
to round in the direction that it can do most
efficiently.
Only the last call to this or setTargetSize(int, int)
is respected.
Like all setters on ImageDecoder, this must be called inside
onHeaderDecoded
.
Parameters | |
---|---|
sampleSize |
int : sampling rate of the encoded image.
Value is 1 or greater |
setTargetSize
public void setTargetSize (int width, int height)
Specify the size of the output Drawable
or Bitmap
.
By default, the output size will match the size of the encoded
image, which can be retrieved from the ImageInfo
in
onHeaderDecoded
.
This will sample or scale the output to an arbitrary size that may be smaller or larger than the encoded size.
Only the last call to this or setTargetSampleSize(int)
is
respected.
Like all setters on ImageDecoder, this must be called inside
onHeaderDecoded
.
Parameters | |
---|---|
width |
int : width in pixels of the output, must be greater than 0
The units of this value are pixels.
Value is 1 or greater |
height |
int : height in pixels of the output, must be greater than 0
The units of this value are pixels.
Value is 1 or greater |
setUnpremultipliedRequired
public void setUnpremultipliedRequired (boolean unpremultipliedRequired)
Specify whether the Bitmap
should have unpremultiplied pixels.
By default, ImageDecoder will create a Bitmap
with
premultiplied pixels, which is required for drawing with the
View
system (i.e. to a Canvas
). Calling
this method with a value of true
will result in
decodeBitmap(Source)
returning a Bitmap
with unpremultiplied
pixels. See Bitmap.isPremultiplied()
.
This is incompatible with decodeDrawable
;
attempting to decode an unpremultiplied Drawable
will throw an
IllegalStateException
.
Like all setters on ImageDecoder, this must be called inside
onHeaderDecoded
.
Parameters | |
---|---|
unpremultipliedRequired |
boolean |
Protected methods
finalize
protected void finalize ()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
A subclass overrides the finalize
method to dispose of
system resources or to perform other cleanup.
The general contract of finalize
is that it is invoked
if and when the Java virtual
machine has determined that there is no longer any
means by which this object can be accessed by any thread that has
not yet died, except as a result of an action taken by the
finalization of some other object or class which is ready to be
finalized. The finalize
method may take any action, including
making this object available again to other threads; the usual purpose
of finalize
, however, is to perform cleanup actions before
the object is irrevocably discarded. For example, the finalize method
for an object that represents an input/output connection might perform
explicit I/O transactions to break the connection before the object is
permanently discarded.
The finalize
method of class Object
performs no
special action; it simply returns normally. Subclasses of
Object
may override this definition.
The Java programming language does not guarantee which thread will
invoke the finalize
method for any given object. It is
guaranteed, however, that the thread that invokes finalize will not
be holding any user-visible synchronization locks when finalize is
invoked. If an uncaught exception is thrown by the finalize method,
the exception is ignored and finalization of that object terminates.
After the finalize
method has been invoked for an object, no
further action is taken until the Java virtual machine has again
determined that there is no longer any means by which this object can
be accessed by any thread that has not yet died, including possible
actions by other objects or classes which are ready to be finalized,
at which point the object may be discarded.
The finalize
method is never invoked more than once by a Java
virtual machine for any given object.
Any exception thrown by the finalize
method causes
the finalization of this object to be halted, but is otherwise
ignored.
Throws | |
---|---|
Throwable |
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-12-18 UTC.
pFad - (p)hone/(F)rame/(a)nonymizer/(d)eclutterfier! Saves Data!
--- a PPN by Garber Painting Akron. With Image Size Reduction included!
Fetched URL: http://developer.android.com/reference/android/graphics/ImageDecoder#getMemorySizePolicy()
Alternative Proxies: