A class for converting encoded images (like {@code PNG}, {@code JPEG}, * {@code WEBP}, {@code GIF}, or {@code HEIF}) into {@link Drawable} or * {@link Bitmap} objects. * *
To use it, first create a {@link Source Source} using one of the * {@code createSource} overloads. For example, to decode from a {@link Uri}, call * {@link #createSource(ContentResolver, Uri)} and pass the result to * {@link #decodeDrawable(Source)} or {@link #decodeBitmap(Source)}: * *
* File file = new File(...); * ImageDecoder.Source source = ImageDecoder.createSource(file); * Drawable drawable = ImageDecoder.decodeDrawable(source); ** *
To change the default settings, pass the {@link Source Source} and an * {@link OnHeaderDecodedListener OnHeaderDecodedListener} to * {@link #decodeDrawable(Source, OnHeaderDecodedListener)} or * {@link #decodeBitmap(Source, OnHeaderDecodedListener)}. For example, to * create a sampled image with half the width and height of the original image, * call {@link #setTargetSampleSize setTargetSampleSize(2)} inside * {@link OnHeaderDecodedListener#onHeaderDecoded onHeaderDecoded}: * *
* OnHeaderDecodedListener listener = new OnHeaderDecodedListener() {
* public void onHeaderDecoded(ImageDecoder decoder, ImageInfo info, Source source) {
* decoder.setTargetSampleSize(2);
* }
* };
* Drawable drawable = ImageDecoder.decodeDrawable(source, listener);
*
*
* The {@link ImageInfo ImageInfo} contains information about the encoded image, like * its width and height, and the {@link Source Source} can be used to match to a particular * {@link Source Source} if a single {@link OnHeaderDecodedListener OnHeaderDecodedListener} * is used with multiple {@link Source Source} objects. * *
The {@link OnHeaderDecodedListener 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 {@code GIF} or {@code WEBP}, * {@link #decodeDrawable decodeDrawable} will return an {@link AnimatedImageDrawable}. To * start its animation, call {@link AnimatedImageDrawable#start AnimatedImageDrawable.start()}: * *
* Drawable drawable = ImageDecoder.decodeDrawable(source);
* if (drawable instanceof AnimatedImageDrawable) {
* ((AnimatedImageDrawable) drawable).start();
* }
*
*
* By default, a {@link Bitmap} created by {@link ImageDecoder} (including * one that is inside a {@link Drawable}) will be immutable (i.e. * {@link Bitmap#isMutable Bitmap.isMutable()} returns {@code false}), and it * will typically have {@code Config} {@link Bitmap.Config#HARDWARE}. Although * these properties can be changed with {@link #setMutableRequired setMutableRequired(true)} * (which is only compatible with {@link #decodeBitmap(Source)} and * {@link #decodeBitmap(Source, OnHeaderDecodedListener)}) and {@link #setAllocator}, * it is also possible to apply custom effects regardless of the mutability of * the final returned object by passing a {@link PostProcessor} to * {@link #setPostProcessor setPostProcessor}. A {@link 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 * {@link Exception} occurs during decoding, a {@link DecodeException DecodeException} * will be thrown. In some cases, the {@link ImageDecoder} may have decoded part of * the image. In order to display the partial image, an * {@link OnPartialImageListener OnPartialImageListener} must be passed to * {@link #setOnPartialImageListener 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;
* });
* });
*
*/
public final class ImageDecoder implements AutoCloseable {
/**
* Source of encoded image data.
*
* References the data that will be used to decode a {@link Drawable} * or {@link Bitmap} in {@link #decodeDrawable decodeDrawable} or * {@link #decodeBitmap decodeBitmap}. Constructing a {@code Source} (with * one of the overloads of {@code createSource}) can be done on any thread * because the construction simply captures values. The real work is done * in {@link #decodeDrawable decodeDrawable} or {@link #decodeBitmap decodeBitmap}. * *
A {@code Source} object can be reused to create multiple versions of the * same image. For example, to decode a full size image and its thumbnail, * the same {@code Source} can be used once with no * {@link OnHeaderDecodedListener OnHeaderDecodedListener} and once with an * implementation of {@link OnHeaderDecodedListener#onHeaderDecoded onHeaderDecoded} * that calls {@link #setTargetSize} with smaller dimensions. One {@code Source} * can even be used simultaneously in multiple threads.
*/ public static abstract class Source { private Source() {} @Nullable Resources getResources() { return null; } int getDensity() { return Bitmap.DENSITY_NONE; } final int computeDstDensity() { Resources res = getResources(); if (res == null) { return Bitmap.getDefaultDensity(); } return res.getDisplayMetrics().densityDpi; } @NonNull abstract ImageDecoder createImageDecoder(boolean preferAnimation) throws IOException; }; private static class ByteArraySource extends Source { ByteArraySource(@NonNull byte[] data, int offset, int length) { mData = data; mOffset = offset; mLength = length; }; private final byte[] mData; private final int mOffset; private final int mLength; @Override public ImageDecoder createImageDecoder(boolean preferAnimation) throws IOException { return nCreate(mData, mOffset, mLength, preferAnimation, this); } @Override public String toString() { return "ByteArraySource{len=" + mLength + "}"; } } private static class ByteBufferSource extends Source { ByteBufferSource(@NonNull ByteBuffer buffer) { mBuffer = buffer; mLength = mBuffer.limit() - mBuffer.position(); } private final ByteBuffer mBuffer; private final int mLength; @Override public ImageDecoder createImageDecoder(boolean preferAnimation) throws IOException { if (!mBuffer.isDirect() && mBuffer.hasArray()) { int offset = mBuffer.arrayOffset() + mBuffer.position(); int length = mBuffer.limit() - mBuffer.position(); return nCreate(mBuffer.array(), offset, length, preferAnimation, this); } ByteBuffer buffer = mBuffer.slice(); return nCreate(buffer, buffer.position(), buffer.limit(), preferAnimation, this); } @Override public String toString() { return "ByteBufferSource{len=" + mLength + "}"; } } private static class ContentResolverSource extends Source { ContentResolverSource(@NonNull ContentResolver resolver, @NonNull Uri uri, @Nullable Resources res) { mResolver = resolver; mUri = uri; mResources = res; } private final ContentResolver mResolver; private final Uri mUri; private final Resources mResources; @Nullable Resources getResources() { return mResources; } @Override public ImageDecoder createImageDecoder(boolean preferAnimation) throws IOException { AssetFileDescriptor assetFd = null; try { if (ContentResolver.SCHEME_CONTENT.equals(mUri.getScheme())) { assetFd = mResolver.openTypedAssetFileDescriptor(mUri, "image/*", null); } else { assetFd = mResolver.openAssetFileDescriptor(mUri, "r"); } } catch (FileNotFoundException e) { // Handled below, along with the case where assetFd was set to null. } if (assetFd == null) { // Some images cannot be opened as AssetFileDescriptors (e.g. // bmp, ico). Open them as InputStreams. InputStream is = mResolver.openInputStream(mUri); if (is == null) { throw new FileNotFoundException(mUri.toString()); } return createFromStream(is, true, preferAnimation, this); } return createFromAssetFileDescriptor(assetFd, preferAnimation, this); } @Override public String toString() { String uri = mUri.toString(); if (uri.length() > 90) { // We want to keep the Uri usable - usually the authority and the end is important. uri = uri.substring(0, 80) + ".." + uri.substring(uri.length() - 10); } return "ContentResolverSource{uri=" + uri + "}"; } } @NonNull private static ImageDecoder createFromFile(@NonNull File file, boolean preferAnimation, @NonNull Source source) throws IOException { FileInputStream stream = new FileInputStream(file); FileDescriptor fd = stream.getFD(); try { Os.lseek(fd, 0, SEEK_CUR); } catch (ErrnoException e) { return createFromStream(stream, true, preferAnimation, source); } ImageDecoder decoder = null; try { decoder = nCreate(fd, AssetFileDescriptor.UNKNOWN_LENGTH, preferAnimation, source); } finally { if (decoder == null) { IoUtils.closeQuietly(stream); } else { decoder.mInputStream = stream; decoder.mOwnsInputStream = true; } } return decoder; } @NonNull private static ImageDecoder createFromStream(@NonNull InputStream is, boolean closeInputStream, boolean preferAnimation, Source source) throws IOException { // Arbitrary size matches BitmapFactory. byte[] storage = new byte[16 * 1024]; ImageDecoder decoder = null; try { decoder = nCreate(is, storage, preferAnimation, source); } finally { if (decoder == null) { if (closeInputStream) { IoUtils.closeQuietly(is); } } else { decoder.mInputStream = is; decoder.mOwnsInputStream = closeInputStream; decoder.mTempStorage = storage; } } return decoder; } @NonNull private static ImageDecoder createFromAssetFileDescriptor(@NonNull AssetFileDescriptor assetFd, boolean preferAnimation, Source source) throws IOException { if (assetFd == null) { throw new FileNotFoundException(); } final FileDescriptor fd = assetFd.getFileDescriptor(); final long offset = assetFd.getStartOffset(); ImageDecoder decoder = null; try { try { Os.lseek(fd, offset, SEEK_SET); decoder = nCreate(fd, assetFd.getDeclaredLength(), preferAnimation, source); } catch (ErrnoException e) { decoder = createFromStream(new FileInputStream(fd), true, preferAnimation, source); } } finally { if (decoder == null) { IoUtils.closeQuietly(assetFd); } else { decoder.mAssetFd = assetFd; } } return decoder; } /** * For backwards compatibility, this does *not* close the InputStream. * * Further, unlike other Sources, this one is not reusable. */ private static class InputStreamSource extends Source { InputStreamSource(Resources res, @NonNull InputStream is, int inputDensity) { if (is == null) { throw new IllegalArgumentException("The InputStream cannot be null"); } mResources = res; mInputStream = is; mInputDensity = inputDensity; } final Resources mResources; InputStream mInputStream; final int mInputDensity; @Override public Resources getResources() { return mResources; } @Override public int getDensity() { return mInputDensity; } @Override public ImageDecoder createImageDecoder(boolean preferAnimation) throws IOException { synchronized (this) { if (mInputStream == null) { throw new IOException("Cannot reuse InputStreamSource"); } InputStream is = mInputStream; mInputStream = null; return createFromStream(is, false, preferAnimation, this); } } @Override public String toString() { return "InputStream{s=" + mInputStream + "}"; } } /** * Takes ownership of the AssetInputStream. * * @hide */ public static class AssetInputStreamSource extends Source { public AssetInputStreamSource(@NonNull AssetInputStream ais, @NonNull Resources res, @NonNull TypedValue value) { mAssetInputStream = ais; mResources = res; if (value.density == TypedValue.DENSITY_DEFAULT) { mDensity = DisplayMetrics.DENSITY_DEFAULT; } else if (value.density != TypedValue.DENSITY_NONE) { mDensity = value.density; } else { mDensity = Bitmap.DENSITY_NONE; } } private AssetInputStream mAssetInputStream; private final Resources mResources; private final int mDensity; @Override public Resources getResources() { return mResources; } @Override public int getDensity() { return mDensity; } @Override public ImageDecoder createImageDecoder(boolean preferAnimation) throws IOException { synchronized (this) { if (mAssetInputStream == null) { throw new IOException("Cannot reuse AssetInputStreamSource"); } AssetInputStream ais = mAssetInputStream; mAssetInputStream = null; return createFromAsset(ais, preferAnimation, this); } } @Override public String toString() { return "AssetInputStream{s=" + mAssetInputStream + "}"; } } private static class ResourceSource extends Source { ResourceSource(@NonNull Resources res, int resId) { mResources = res; mResId = resId; mResDensity = Bitmap.DENSITY_NONE; } final Resources mResources; final int mResId; int mResDensity; private Object mLock = new Object(); @Override public Resources getResources() { return mResources; } @Override public int getDensity() { synchronized (mLock) { return mResDensity; } } @Override public ImageDecoder createImageDecoder(boolean preferAnimation) throws IOException { TypedValue value = new TypedValue(); // This is just used in order to access the underlying Asset and // keep it alive. InputStream is = mResources.openRawResource(mResId, value); synchronized (mLock) { if (value.density == TypedValue.DENSITY_DEFAULT) { mResDensity = DisplayMetrics.DENSITY_DEFAULT; } else if (value.density != TypedValue.DENSITY_NONE) { mResDensity = value.density; } } return createFromAsset((AssetInputStream) is, preferAnimation, this); } @Override public String toString() { // Try to return a human-readable name for debugging purposes. try { return "Resource{name=" + mResources.getResourceName(mResId) + "}"; } catch (Resources.NotFoundException e) { // It's ok if we don't find it, fall back to ID. } return "Resource{id=" + mResId + "}"; } } /** * ImageDecoder will own the AssetInputStream. */ private static ImageDecoder createFromAsset(AssetInputStream ais, boolean preferAnimation, Source source) throws IOException { ImageDecoder decoder = null; try { long asset = ais.getNativeAsset(); decoder = nCreate(asset, preferAnimation, source); } finally { if (decoder == null) { IoUtils.closeQuietly(ais); } else { decoder.mInputStream = ais; decoder.mOwnsInputStream = true; } } return decoder; } private static class AssetSource extends Source { AssetSource(@NonNull AssetManager assets, @NonNull String fileName) { mAssets = assets; mFileName = fileName; } private final AssetManager mAssets; private final String mFileName; @Override public ImageDecoder createImageDecoder(boolean preferAnimation) throws IOException { InputStream is = mAssets.open(mFileName); return createFromAsset((AssetInputStream) is, preferAnimation, this); } @Override public String toString() { return "AssetSource{file=" + mFileName + "}"; } } private static class FileSource extends Source { FileSource(@NonNull File file) { mFile = file; } private final File mFile; @Override public ImageDecoder createImageDecoder(boolean preferAnimation) throws IOException { return createFromFile(mFile, preferAnimation, this); } @Override public String toString() { return "FileSource{file=" + mFile + "}"; } } private static class CallableSource extends Source { CallableSource(@NonNull CallableIf {@code true}, {@link #decodeDrawable decodeDrawable} will * return an {@link AnimatedImageDrawable}.
*/ public boolean isAnimated() { return mIsAnimated; } /** * If known, the color space the decoded bitmap will have. Note that the * output color space is not guaranteed to be the color space the bitmap * is encoded with. If not known (when the config is * {@link Bitmap.Config#ALPHA_8} for instance), or there is an error, * it is set to null. */ @Nullable public ColorSpace getColorSpace() { return mColorSpace; } }; /** * Interface for changing the default settings of a decode. * *Supply an instance to * {@link #decodeDrawable(Source, OnHeaderDecodedListener) decodeDrawable} * or {@link #decodeBitmap(Source, OnHeaderDecodedListener) decodeBitmap}, * which will call {@link OnHeaderDecodedListener#onHeaderDecoded onHeaderDecoded} * (in the same thread) once the size is known. The implementation of * {@link OnHeaderDecodedListener#onHeaderDecoded onHeaderDecoded} can then * change the decode settings as desired. */ public static interface OnHeaderDecodedListener { /** * Called by {@link ImageDecoder} when the header has been decoded and * the image size is known. * * @param decoder the object performing the decode, for changing * its default settings. * @param info information about the encoded image. * @param source object that created {@code decoder}. */ public void onHeaderDecoded(@NonNull ImageDecoder decoder, @NonNull ImageInfo info, @NonNull Source source); }; /** * Information about an interrupted decode. */ public static final class DecodeException extends IOException { /** * An Exception was thrown reading the {@link Source}. */ public static final int SOURCE_EXCEPTION = 1; /** * The encoded data was incomplete. */ public static final int SOURCE_INCOMPLETE = 2; /** * The encoded data contained an error. */ public static final int SOURCE_MALFORMED_DATA = 3; /** @hide **/ @Retention(SOURCE) @IntDef(value = { SOURCE_EXCEPTION, SOURCE_INCOMPLETE, SOURCE_MALFORMED_DATA }, prefix = {"SOURCE_"}) public @interface Error {}; @Error final int mError; @NonNull final Source mSource; DecodeException(@Error int error, @Nullable Throwable cause, @NonNull Source source) { super(errorMessage(error, cause), cause); mError = error; mSource = source; } /** * Private method called by JNI. */ @SuppressWarnings("unused") DecodeException(@Error int error, @Nullable String msg, @Nullable Throwable cause, @NonNull Source source) { super(msg + errorMessage(error, cause), cause); mError = error; mSource = source; } /** * Retrieve the reason that decoding was interrupted. * *
If the error is {@link #SOURCE_EXCEPTION}, the underlying * {@link java.lang.Throwable} can be retrieved with * {@link java.lang.Throwable#getCause}.
*/ @Error public int getError() { return mError; } /** * Retrieve the {@link Source Source} that was interrupted. * *This can be used for equality checking to find the Source which * failed to completely decode.
*/ @NonNull public Source getSource() { return mSource; } private static String errorMessage(@Error int error, @Nullable Throwable cause) { switch (error) { case SOURCE_EXCEPTION: return "Exception in input: " + cause; case SOURCE_INCOMPLETE: return "Input was incomplete."; case SOURCE_MALFORMED_DATA: return "Input contained an error."; default: return ""; } } } /** * Interface for inspecting a {@link DecodeException DecodeException} * and potentially preventing it from being thrown. * *If an instance is passed to * {@link #setOnPartialImageListener setOnPartialImageListener}, a * {@link DecodeException DecodeException} that would otherwise have been * thrown can be inspected inside * {@link OnPartialImageListener#onPartialImage onPartialImage}. * If {@link OnPartialImageListener#onPartialImage onPartialImage} returns * {@code true}, a partial image will be created. */ public static interface OnPartialImageListener { /** * Called by {@link ImageDecoder} when there is only a partial image to * display. * *
If decoding is interrupted after having decoded a partial image, * this method will be called. The implementation can inspect the * {@link DecodeException DecodeException} and optionally finish the * rest of the decode creation process to create a partial {@link Drawable} * or {@link Bitmap}. * * @param exception exception containing information about the * decode interruption. * @return {@code true} to create and return a {@link Drawable} or * {@link Bitmap} with partial data. {@code false} (which is the * default) to abort the decode and throw {@code e}. Any undecoded * lines in the image will be blank. */ boolean onPartialImage(@NonNull DecodeException exception); }; // Fields private long mNativePtr; private final int mWidth; private final int mHeight; private final boolean mAnimated; private final boolean mIsNinePatch; private int mDesiredWidth; private int mDesiredHeight; private int mAllocator = ALLOCATOR_DEFAULT; private boolean mUnpremultipliedRequired = false; private boolean mMutable = false; private boolean mConserveMemory = false; private boolean mDecodeAsAlphaMask = false; private ColorSpace mDesiredColorSpace = null; private Rect mCropRect; private Rect mOutPaddingRect; private Source mSource; private PostProcessor mPostProcessor; private OnPartialImageListener mOnPartialImageListener; // Objects for interacting with the input. private InputStream mInputStream; private boolean mOwnsInputStream; private byte[] mTempStorage; private AssetFileDescriptor mAssetFd; private final AtomicBoolean mClosed = new AtomicBoolean(); private final CloseGuard mCloseGuard = CloseGuard.get(); /** * Private constructor called by JNI. {@link #close} must be * called after decoding to delete native resources. */ @SuppressWarnings("unused") private ImageDecoder(long nativePtr, int width, int height, boolean animated, boolean isNinePatch) { mNativePtr = nativePtr; mWidth = width; mHeight = height; mDesiredWidth = width; mDesiredHeight = height; mAnimated = animated; mIsNinePatch = isNinePatch; mCloseGuard.open("close"); } @Override protected void finalize() throws Throwable { try { if (mCloseGuard != null) { mCloseGuard.warnIfOpen(); } // Avoid closing these in finalizer. mInputStream = null; mAssetFd = null; close(); } finally { super.finalize(); } } /** * 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 {@link ContentResolver#openTypedAssetFile}. */ public static boolean isMimeTypeSupported(@NonNull String mimeType) { Objects.requireNonNull(mimeType); switch (mimeType.toLowerCase(Locale.US)) { case "image/png": case "image/jpeg": case "image/webp": case "image/gif": case "image/bmp": case "image/x-ico": case "image/vnd.wap.wbmp": case "image/x-sony-arw": case "image/x-canon-cr2": case "image/x-adobe-dng": case "image/x-nikon-nef": case "image/x-nikon-nrw": case "image/x-olympus-orf": case "image/x-fuji-raf": case "image/x-panasonic-rw2": case "image/x-pentax-pef": case "image/x-samsung-srw": return true; case "image/heif": case "image/heic": return isHevcDecoderSupported(); case "image/avif": return isP010SupportedForAV1(); default: return false; } } /** * Create a new {@link Source Source} from a resource. * * @param res the {@link Resources} object containing the image data. * @param resId resource ID of the image data. * @return a new Source object, which can be passed to * {@link #decodeDrawable decodeDrawable} or * {@link #decodeBitmap decodeBitmap}. */ @AnyThread @NonNull public static Source createSource(@NonNull Resources res, int resId) { return new ResourceSource(res, resId); } /** * Create a new {@link Source Source} from a {@link android.net.Uri}. * *
Note: If this {@code Source} is passed to {@link #decodeDrawable decodeDrawable}, * and the encoded image is animated, the returned {@link AnimatedImageDrawable} * will continue reading from {@code data}, so its contents must not * be modified, even after the {@code AnimatedImageDrawable} is returned. * {@code data}'s contents should never be modified during decode.
* * @param data byte array of compressed image data. * @param offset offset into data for where the decoder should begin * parsing. * @param length number of bytes, beginning at offset, to parse. * @return a new Source object, which can be passed to * {@link #decodeDrawable decodeDrawable} or * {@link #decodeBitmap decodeBitmap}. * @throws NullPointerException if data is null. * @throws ArrayIndexOutOfBoundsException if offset and length are * not within data. */ @AnyThread @NonNull public static Source createSource(@NonNull byte[] data, int offset, int length) throws ArrayIndexOutOfBoundsException { if (data == null) { throw new NullPointerException("null byte[] in createSource!"); } if (offset < 0 || length < 0 || offset >= data.length || offset + length > data.length) { throw new ArrayIndexOutOfBoundsException( "invalid offset/length!"); } return new ByteArraySource(data, offset, length); } /** * Create a new {@link Source Source} from a byte array. * *Note: If this {@code Source} is passed to {@link #decodeDrawable decodeDrawable}, * and the encoded image is animated, the returned {@link AnimatedImageDrawable} * will continue reading from {@code data}, so its contents must not * be modified, even after the {@code AnimatedImageDrawable} is returned. * {@code data}'s contents should never be modified during decode.
* * @param data byte array of compressed image data. * @return a new Source object, which can be passed to * {@link #decodeDrawable decodeDrawable} or * {@link #decodeBitmap decodeBitmap}. * @throws NullPointerException if data is null. */ @AnyThread @NonNull public static Source createSource(@NonNull byte[] data) { return createSource(data, 0, data.length); } /** * Create a new {@link Source Source} from a {@link java.nio.ByteBuffer}. * *Decoding will start from {@link java.nio.ByteBuffer#position() buffer.position()}. * The position of {@code buffer} will not be affected.
* *Note: If this {@code Source} is passed to {@link #decodeDrawable decodeDrawable}, * and the encoded image is animated, the returned {@link AnimatedImageDrawable} * will continue reading from the {@code buffer}, so its contents must not * be modified, even after the {@code AnimatedImageDrawable} is returned. * {@code buffer}'s contents should never be modified during decode.
* * @return a new Source object, which can be passed to * {@link #decodeDrawable decodeDrawable} or * {@link #decodeBitmap decodeBitmap}. */ @AnyThread @NonNull public static Source createSource(@NonNull ByteBuffer buffer) { return new ByteBufferSource(buffer); } /** * Internal API used to generate bitmaps for use by Drawables (i.e. BitmapDrawable) * *Unlike other Sources, this one cannot be reused.
* * @hide */ @AnyThread @NonNull public static Source createSource(Resources res, @NonNull InputStream is) { return new InputStreamSource(res, is, Bitmap.getDefaultDensity()); } /** * Internal API used to generate bitmaps for use by Drawables (i.e. BitmapDrawable) * *Unlike other Sources, this one cannot be reused.
* * @hide */ @AnyThread @TestApi @NonNull public static Source createSource(Resources res, @NonNull InputStream is, int density) { return new InputStreamSource(res, is, density); } /** * Create a new {@link Source Source} from a {@link java.io.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 * {@link #createSource(Callable)} or * {@link #createSource(ContentResolver, Uri)}. * @return a new Source object, which can be passed to * {@link #decodeDrawable decodeDrawable} or * {@link #decodeBitmap decodeBitmap}. */ @AnyThread @NonNull public static Source createSource(@NonNull File file) { return new FileSource(file); } /** * Create a new {@link Source Source} from a {@link Callable} that returns a * new {@link AssetFileDescriptor} for each request. This provides control * over how the {@link AssetFileDescriptor} is created, such as passing * options into {@link ContentResolver#openTypedAssetFileDescriptor}, or * enabling use of a {@link android.os.CancellationSignal}. *
* It's important for the given {@link Callable} to return a new, unique
* {@link AssetFileDescriptor} for each invocation, to support reuse of the
* returned {@link Source Source}.
*
* @return a new Source object, which can be passed to
* {@link #decodeDrawable decodeDrawable} or {@link #decodeBitmap
* decodeBitmap}.
*/
@AnyThread
@NonNull
public static Source createSource(@NonNull Callable This takes an input that functions like
* {@link BitmapFactory.Options#inSampleSize}. It returns a width and
* height that can be achieved by sampling the encoded image. Other widths
* and heights may be supported, but will require an additional (internal)
* scaling step. Such internal scaling is *not* supported with
* {@link #setUnpremultipliedRequired} set to {@code true}. By default, the output size will match the size of the encoded
* image, which can be retrieved from the {@link ImageInfo ImageInfo} in
* {@link OnHeaderDecodedListener#onHeaderDecoded 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 {@link #setTargetSampleSize} is
* respected. Like all setters on ImageDecoder, this must be called inside
* {@link OnHeaderDecodedListener#onHeaderDecoded onHeaderDecoded}. By default, the output size will match the size of the encoded
* image, which can be retrieved from the {@link ImageInfo ImageInfo} in
* {@link OnHeaderDecodedListener#onHeaderDecoded onHeaderDecoded}. Requests the decoder to subsample the original image, returning a
* smaller image to save memory. The {@code sampleSize} is the number of pixels
* in either dimension that correspond to a single pixel in the output.
* For example, {@code sampleSize == 4} returns an image that is 1/4 the
* width/height of the original, and 1/16 the number of pixels. Must be greater than or equal to 1. This has the same effect as calling {@link #setTargetSize} with
* dimensions based on the {@code sampleSize}. Unlike dividing the original
* width and height by the {@code sampleSize} manually, calling this method
* allows {@code ImageDecoder} to round in the direction that it can do most
* efficiently. Only the last call to this or {@link #setTargetSize} is respected. Like all setters on ImageDecoder, this must be called inside
* {@link OnHeaderDecodedListener#onHeaderDecoded onHeaderDecoded}. Useful for drawing to a software {@link Canvas} or for
* accessing the pixels on the final output.
*/
public static final int ALLOCATOR_SOFTWARE = 1;
/**
* Use shared memory for the pixel memory.
*
* Useful for sharing across processes.
*/
public static final int ALLOCATOR_SHARED_MEMORY = 2;
/**
* Require a {@link Bitmap.Config#HARDWARE} {@link Bitmap}.
*
* When this is combined with incompatible options, like
* {@link #setMutableRequired setMutableRequired(true)} or
* {@link #setDecodeAsAlphaMaskEnabled setDecodeAsAlphaMaskEnabled(true)},
* {@link #decodeDrawable decodeDrawable} or {@link #decodeBitmap decodeBitmap}
* will throw an {@link java.lang.IllegalStateException}.
*/
public static final int ALLOCATOR_HARDWARE = 3;
/** @hide **/
@Retention(SOURCE)
@IntDef(value = { ALLOCATOR_DEFAULT, ALLOCATOR_SOFTWARE,
ALLOCATOR_SHARED_MEMORY, ALLOCATOR_HARDWARE },
prefix = {"ALLOCATOR_"})
public @interface Allocator {};
/**
* Choose the backing for the pixel memory.
*
* This is ignored for animated drawables. Like all setters on ImageDecoder, this must be called inside
* {@link OnHeaderDecodedListener#onHeaderDecoded onHeaderDecoded}. By default, ImageDecoder will create a {@link Bitmap} with
* premultiplied pixels, which is required for drawing with the
* {@link android.view.View} system (i.e. to a {@link Canvas}). Calling
* this method with a value of {@code true} will result in
* {@link #decodeBitmap} returning a {@link Bitmap} with unpremultiplied
* pixels. See {@link Bitmap#isPremultiplied Bitmap.isPremultiplied()}.
* This is incompatible with {@link #decodeDrawable decodeDrawable};
* attempting to decode an unpremultiplied {@link Drawable} will throw an
* {@link java.lang.IllegalStateException}. Like all setters on ImageDecoder, this must be called inside
* {@link OnHeaderDecodedListener#onHeaderDecoded onHeaderDecoded}. This allows adding effects prior to returning a {@link Drawable} or
* {@link Bitmap}. For a {@code Drawable} or an immutable {@code Bitmap},
* this is the only way to process the image after decoding. If combined with {@link #setTargetSize} and/or {@link #setCrop},
* {@link 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
* {@link Canvas} will be recorded immediately and then applied to each
* frame. Like all setters on ImageDecoder, this must be called inside
* {@link OnHeaderDecodedListener#onHeaderDecoded onHeaderDecoded}. Will be called if there is an error in the input. Without one, an
* error will result in an {@code Exception} being thrown. Like all setters on ImageDecoder, this must be called inside
* {@link OnHeaderDecodedListener#onHeaderDecoded onHeaderDecoded}. {@code subset} must be contained within the size set by
* {@link #setTargetSize} or the bounds of the image if setTargetSize was
* not called. Otherwise an {@link IllegalStateException} will be thrown by
* {@link #decodeDrawable decodeDrawable}/{@link #decodeBitmap decodeBitmap}. NOT intended as a replacement for
* {@link BitmapRegionDecoder#decodeRegion BitmapRegionDecoder.decodeRegion()}.
* This supports all formats, but merely crops the output. Like all setters on ImageDecoder, this must be called inside
* {@link OnHeaderDecodedListener#onHeaderDecoded onHeaderDecoded}. Like all setters on ImageDecoder, this must be called inside
* {@link OnHeaderDecodedListener#onHeaderDecoded onHeaderDecoded}. By default, a {@link Bitmap} created by {@link #decodeBitmap decodeBitmap}
* will be immutable i.e. {@link Bitmap#isMutable() Bitmap.isMutable()} returns
* {@code false}. This can be changed with {@code setMutableRequired(true)}.
*
* Mutable Bitmaps are incompatible with {@link #ALLOCATOR_HARDWARE},
* because {@link Bitmap.Config#HARDWARE} Bitmaps cannot be mutable.
* Attempting to combine them will throw an
* {@link java.lang.IllegalStateException}. Mutable Bitmaps are also incompatible with {@link #decodeDrawable decodeDrawable},
* which would require retrieving the Bitmap from the returned Drawable in
* order to modify. Attempting to decode a mutable {@link Drawable} will
* throw an {@link java.lang.IllegalStateException}. Like all setters on ImageDecoder, this must be called inside
* {@link OnHeaderDecodedListener#onHeaderDecoded onHeaderDecoded}. For example an opaque 8-bit image may be compressed into an
* {@link Bitmap.Config#RGB_565} configuration, sacrificing image
* quality to save memory.
*/
public static final int MEMORY_POLICY_LOW_RAM = 0;
/**
* Use the most natural {@link Bitmap.Config} for the internal {@link Bitmap}.
*
* This is the recommended default for most applications and usages. This
* will use the closest {@link Bitmap.Config} for the encoded source. If the
* encoded source does not exactly match any {@link Bitmap.Config}, the next
* highest quality {@link Bitmap.Config} will be used avoiding any loss in
* image quality.
*/
public static final int MEMORY_POLICY_DEFAULT = 1;
/** @hide **/
@Retention(SOURCE)
@IntDef(value = { MEMORY_POLICY_DEFAULT, MEMORY_POLICY_LOW_RAM },
prefix = {"MEMORY_POLICY_"})
public @interface MemoryPolicy {};
/**
* Specify the memory policy for the decoded {@link Bitmap}.
*
* Like all setters on ImageDecoder, this must be called inside
* {@link OnHeaderDecodedListener#onHeaderDecoded onHeaderDecoded}. If this is set to {@code 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 {@link #ALLOCATOR_HARDWARE}. Trying to
* combine them will result in {@link #decodeDrawable decodeDrawable}/
* {@link #decodeBitmap decodeBitmap} throwing an
* {@link java.lang.IllegalStateException}. Like all setters on ImageDecoder, this must be called inside
* {@link OnHeaderDecodedListener#onHeaderDecoded onHeaderDecoded}. This returns whether {@link #setDecodeAsAlphaMaskEnabled} was set to
* {@code true}. It may still return {@code true} even if the image has
* more than one channel and therefore will not be treated as an alpha
* mask. If non-null, the decoder will try to decode into {@code 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
* {@link ColorSpace} best suited for the requested image configuration
* (for instance {@link ColorSpace.Named#SRGB sRGB} for the
* {@link Bitmap.Config#ARGB_8888} configuration and
* {@link ColorSpace.Named#EXTENDED_SRGB EXTENDED_SRGB} for
* {@link Bitmap.Config#RGBA_F16}). Only {@link ColorSpace.Model#RGB} color spaces are
* currently supported. An Prior to {@link android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE},
* the specified color space's transfer function must be
* an {@link ColorSpace.Rgb.TransferParameters ICC parametric curve}. An
* Like all setters on ImageDecoder, this must be called inside
* {@link OnHeaderDecodedListener#onHeaderDecoded onHeaderDecoded}. This is an implementation detail of {@link ImageDecoder}, and should
* never be called manually. Returns the same {@link ImageInfo} object that a usual decoding process would return as
* part of {@link OnHeaderDecodedListener}.
*
* @param src representing the encoded image.
* @return ImageInfo describing the image.
* @throws IOException if {@code src} is not found, is an unsupported format, or cannot be
* decoded for any reason.
* @hide
*/
@WorkerThread
@NonNull
public static ImageInfo decodeHeader(@NonNull Source src) throws IOException {
Trace.traceBegin(Trace.TRACE_TAG_RESOURCES, "ImageDecoder#decodeHeader");
try (ImageDecoder decoder = src.createImageDecoder(true /*preferAnimation*/)) {
// We don't want to leak decoder so resolve all properties immediately.
return new ImageInfo(
new Size(decoder.mWidth, decoder.mHeight),
decoder.mAnimated,
decoder.getMimeType(),
decoder.getColorSpace());
} finally {
// Close the ImageDecoder#decodeHeader trace.
Trace.traceEnd(Trace.TRACE_TAG_RESOURCES);
}
}
/**
* Create a {@link Drawable} from a {@code Source}.
*
* @param src representing the encoded image.
* @param listener for learning the {@link ImageInfo ImageInfo} and changing any
* default settings on the {@code ImageDecoder}. This will be called on
* the same thread as {@code decodeDrawable} before that method returns.
* This is required in order to change any of the default settings.
* @return Drawable for displaying the image.
* @throws IOException if {@code src} is not found, is an unsupported
* format, or cannot be decoded for any reason.
*/
@WorkerThread
@NonNull
public static Drawable decodeDrawable(@NonNull Source src,
@NonNull OnHeaderDecodedListener listener) throws IOException {
if (listener == null) {
throw new IllegalArgumentException("listener cannot be null! "
+ "Use decodeDrawable(Source) to not have a listener");
}
return decodeDrawableImpl(src, listener);
}
@WorkerThread
@NonNull
private static Drawable decodeDrawableImpl(@NonNull Source src,
@Nullable OnHeaderDecodedListener listener) throws IOException {
Trace.traceBegin(Trace.TRACE_TAG_RESOURCES, "ImageDecoder#decodeDrawable");
try (ImageDecoder decoder = src.createImageDecoder(true /*preferAnimation*/)) {
decoder.mSource = src;
decoder.callHeaderDecoded(listener, src);
try (ImageDecoderSourceTrace unused = new ImageDecoderSourceTrace(decoder)) {
if (decoder.mUnpremultipliedRequired) {
// Though this could be supported (ignored) for opaque images,
// it seems better to always report this error.
throw new IllegalStateException(
"Cannot decode a Drawable with unpremultiplied pixels!");
}
if (decoder.mMutable) {
throw new IllegalStateException("Cannot decode a mutable Drawable!");
}
// this call potentially manipulates the decoder so it must be performed prior to
// decoding the bitmap and after decode set the density on the resulting bitmap
final int srcDensity = decoder.computeDensity(src);
if (decoder.mAnimated) {
// AnimatedImageDrawable calls postProcessAndRelease only if
// mPostProcessor exists.
ImageDecoder postProcessPtr = decoder.mPostProcessor == null ? null : decoder;
decoder.checkState(true);
Drawable d = new AnimatedImageDrawable(decoder.mNativePtr,
postProcessPtr, decoder.mDesiredWidth,
decoder.mDesiredHeight, decoder.getColorSpacePtr(),
decoder.checkForExtended(), srcDensity,
src.computeDstDensity(), decoder.mCropRect,
decoder.mInputStream, decoder.mAssetFd);
// d has taken ownership of these objects.
decoder.mInputStream = null;
decoder.mAssetFd = null;
return d;
}
Bitmap bm = decoder.decodeBitmapInternal();
bm.setDensity(srcDensity);
Resources res = src.getResources();
byte[] np = bm.getNinePatchChunk();
if (np != null && NinePatch.isNinePatchChunk(np)) {
Rect opticalInsets = new Rect();
bm.getOpticalInsets(opticalInsets);
Rect padding = decoder.mOutPaddingRect;
if (padding == null) {
padding = new Rect();
}
nGetPadding(decoder.mNativePtr, padding);
return new NinePatchDrawable(res, bm, np, padding,
opticalInsets, null);
}
return new BitmapDrawable(res, bm);
}
} finally {
// Close the ImageDecoder#decode trace.
Trace.traceEnd(Trace.TRACE_TAG_RESOURCES);
}
}
/**
* Create a {@link Drawable} from a {@code Source}.
*
* Since there is no {@link OnHeaderDecodedListener OnHeaderDecodedListener},
* the default settings will be used. In order to change any settings, call
* {@link #decodeDrawable(Source, OnHeaderDecodedListener)} instead. Since there is no {@link OnHeaderDecodedListener OnHeaderDecodedListener},
* the default settings will be used. In order to change any settings, call
* {@link #decodeBitmap(Source, OnHeaderDecodedListener)} instead.IllegalArgumentException will
* be thrown by {@link #decodeDrawable decodeDrawable}/
* {@link #decodeBitmap decodeBitmap} when setting a non-RGB color space
* such as {@link ColorSpace.Named#CIE_LAB Lab}.IllegalArgumentException will be thrown by the decode methods
* if calling {@link ColorSpace.Rgb#getTransferParameters()} on the
* specified color space returns null.
* Starting from {@link android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE},
* the color spaces with non ICC parametric curve transfer function are allowed.
* E.g., {@link ColorSpace.Named#BT2020_HLG BT2020_HLG}.
*