1package com.bumptech.glide.load.engine.bitmap_recycle;
2
3import android.graphics.Bitmap;
4
5/**
6 * An interface for a pool that allows users to reuse {@link android.graphics.Bitmap} objects.
7 */
8public interface BitmapPool {
9
10    /**
11     * Returns the current maximum size of the pool in bytes.
12     */
13    int getMaxSize();
14
15    /**
16     * Multiplies the initial size of the pool by the given multipler to dynamically and synchronously allow users to
17     * adjust the size of the pool.
18     *
19     * <p>
20     *     If the current total size of the pool is larger than the max size after the given multiplier is applied,
21     *     {@link Bitmap}s should be evicted until the pool is smaller than the new max size.
22     * </p>
23     *
24     * @param sizeMultiplier The size multiplier to apply between 0 and 1.
25     */
26    void setSizeMultiplier(float sizeMultiplier);
27
28    /**
29     * Adds the given {@link android.graphics.Bitmap} and returns {@code true} if the {@link android.graphics.Bitmap}
30     * was eligible to be added and {@code false} otherwise.
31     *
32     * <p>
33     *     Note - If the {@link android.graphics.Bitmap} is rejected (this method returns false) then it is the caller's
34     *     responsibility to call {@link android.graphics.Bitmap#recycle()}.
35     * </p>
36     *
37     * <p>
38     *     Note - This method will return {@code true} if the given {@link android.graphics.Bitmap} is synchronously
39     *     evicted after being accepted. The only time this method will return {@code false} is if the
40     *     {@link android.graphics.Bitmap} is not eligible to be added to the pool (either it is not mutable or it is
41     *     larger than the max pool size).
42     * </p>
43     *
44     * @see android.graphics.Bitmap#isMutable()
45     * @see android.graphics.Bitmap#recycle()
46     *
47     * @param bitmap The {@link android.graphics.Bitmap} to attempt to add.
48     */
49    boolean put(Bitmap bitmap);
50
51    /**
52     * Returns a {@link android.graphics.Bitmap} of exactly the given width, height, and configuration, and containing
53     * only transparent pixels or null if no such {@link android.graphics.Bitmap} could be obtained from the pool.
54     *
55     * <p>
56     *     Because this method erases all pixels in the {@link Bitmap}, this method is slightly slower than
57     *     {@link #getDirty(int, int, android.graphics.Bitmap.Config)}. If the {@link android.graphics.Bitmap} is being
58     *     obtained to be used in {@link android.graphics.BitmapFactory} or in any other case where every pixel in the
59     *     {@link android.graphics.Bitmap} will always be overwritten or cleared,
60     *     {@link #getDirty(int, int, android.graphics.Bitmap.Config)} will be faster. When in doubt, use this method
61     *     to ensure correctness.
62     * </p>
63     *
64     * <pre>
65     *     Implementations can should clear out every returned Bitmap using the following:
66     *
67     * {@code
68     * bitmap.eraseColor(Color.TRANSPARENT);
69     * }
70     * </pre>
71     *
72     * @see #getDirty(int, int, android.graphics.Bitmap.Config)
73     *
74     * @param width The width in pixels of the desired {@link android.graphics.Bitmap}.
75     * @param height The height in pixels of the desired {@link android.graphics.Bitmap}.
76     * @param config The {@link android.graphics.Bitmap.Config} of the desired {@link android.graphics.Bitmap}.
77     */
78    Bitmap get(int width, int height, Bitmap.Config config);
79
80    /**
81     * Identical to {@link #get(int, int, android.graphics.Bitmap.Config)} except that any returned non-null
82     * {@link android.graphics.Bitmap} may <em>not</em> have been erased and may contain random data.
83     *
84     * <p>
85     *     Although this method is slightly more efficient than {@link #get(int, int, android.graphics.Bitmap.Config)}
86     *     it should be used with caution and only when the caller is sure that they are going to erase the
87     *     {@link android.graphics.Bitmap} entirely before writing new data to it.
88     * </p>
89     *
90     * @see #get(int, int, android.graphics.Bitmap.Config)
91     *
92     * @param width The width in pixels of the desired {@link android.graphics.Bitmap}.
93     * @param height The height in pixels of the desired {@link android.graphics.Bitmap}.
94     * @param config The {@link android.graphics.Bitmap.Config} of the desired {@link android.graphics.Bitmap}.
95     * @return A {@link android.graphics.Bitmap} with exactly the given width, height, and config potentially containing
96     * random image data or null if no such {@link android.graphics.Bitmap} could be obtained from the pool.
97     */
98    Bitmap getDirty(int width, int height, Bitmap.Config config);
99
100    /**
101     * Removes all {@link android.graphics.Bitmap}s from the pool.
102     */
103    void clearMemory();
104
105    /**
106     * Reduces the size of the cache by evicting items based on the given level.
107     *
108     * @see android.content.ComponentCallbacks2
109     *
110     * @param level The level from {@link android.content.ComponentCallbacks2} to use to determine how many
111     * {@link android.graphics.Bitmap}s to evict.
112     */
113    void trimMemory(int level);
114}
115