com.isaacrf.epicbitmaprenderer.core

Class EpicBitmapRenderer

java.lang.Object

com.isaacrf.epicbitmaprenderer.core.EpicBitmapRenderer

public final class EpicBitmapRenderer
extends java.lang.Object

Decode and render Bitmaps the epic and easy way, creating faster Android apps without extra effort.

This Android Bitmap decoder library follows the Google conventions for displaying bitmaps efficiently (see Google guide for more info), offering these features:

• Exposes static asynchronous (and synchronous too, just in case you need it) methods to decode Bitmap objects from different sources out of UI thread, ensuring that your app runs smoothly.
• Image auto and manual downsampling. This library keeps memory usage of your app low by loading images in just the scale and size you need, only specifying Image holder's size (Or a manual downsample rate). If device is still unable to load image due to low memory available, render methods will automatically recalculate image downsample for it to successfully fit on device's memory, avoiding that annoying OutOfMemoryError
• Image auto caching. Rendering methods automatically save rendered Bitmaps in memory and disk caches using dual cache EpicBitmapCache. If an image is previously rendered, next time it will be extracted from cache if available, and it will be used instead of re-rendering Bitmap from source again. This entire process is automatic, as render methods handle cache themselves, and saves a lot of memory consumption from heavy processes like rendering images from disk or internet.

Method Summary

Modifier and Type	Method and Description
static int	calculateInSampleSize(android.graphics.BitmapFactory.Options options, int reqWidth, int reqHeight) Calculates downsample rate, if needed, for an image depending of width and height it should fit on.
static android.graphics.Bitmap	decodeBitmapFromFile(java.lang.String path) Decodes a Bitmap object from a given file, at its original dimensions.
static android.graphics.Bitmap	decodeBitmapFromFile(java.lang.String path, int inSampleSize) Decodes a sampled Bitmap object from a given file, using the inSampleSize specified.
static android.graphics.Bitmap	decodeBitmapFromFile(java.lang.String path, int reqWidth, int reqHeight) Decodes a Bitmap object from a given file, using the specified measures to calculate image downsample if needed.
static void	decodeBitmapFromFile(java.lang.String path, int reqWidth, int reqHeight, OnBitmapRendered onBitmapRendered, OnBitmapRenderFailed onBitmapRenderFailed) Decodes a sampled Bitmap object from a given file asynchronously, using the specified measures to calculate image downsample if needed.
static void	decodeBitmapFromFile(java.lang.String path, int inSampleSize, OnBitmapRendered onBitmapRendered, OnBitmapRenderFailed onBitmapRenderFailed) Decodes a sampled Bitmap object from a given file asynchronously, using the inSampleSize specified.
static void	decodeBitmapFromFile(java.lang.String path, OnBitmapRendered onBitmapRendered, OnBitmapRenderFailed onBitmapRenderFailed) Decodes a Bitmap object from a given file asynchronously, at its original dimensions.
static android.graphics.Bitmap	decodeBitmapFromResource(android.content.res.Resources res, int resId) Decodes a Bitmap object from a given app resource, at its original dimensions.
static android.graphics.Bitmap	decodeBitmapFromResource(android.content.res.Resources res, int resId, int inSampleSize) Decodes a sampled Bitmap object from a given app resource, using the inSampleSize specified.
static android.graphics.Bitmap	decodeBitmapFromResource(android.content.res.Resources res, int resId, int reqWidth, int reqHeight) Decodes a sampled Bitmap object from a given app resource, using the specified measures to calculate image downsample if needed.
static void	decodeBitmapFromResource(android.content.res.Resources res, int resId, int reqWidth, int reqHeight, OnBitmapRendered onBitmapRendered, OnBitmapRenderFailed onBitmapRenderFailed) Decodes a sampled Bitmap object from a given app resource asynchronously, using the specified measures to calculate image downsample if needed.
static void	decodeBitmapFromResource(android.content.res.Resources res, int resId, int inSampleSize, OnBitmapRendered onBitmapRendered, OnBitmapRenderFailed onBitmapRenderFailed) Decodes a sampled Bitmap object from a given app resource asynchronously, using the inSampleSize specified.
static void	decodeBitmapFromResource(android.content.res.Resources res, int resId, OnBitmapRendered onBitmapRendered, OnBitmapRenderFailed onBitmapRenderFailed) Decodes a Bitmap object from a given app resource asynchronously, at its original dimensions.
static void	decodeBitmapFromUrl(java.lang.String url, int reqWidth, int reqHeight, OnBitmapRendered onBitmapRendered, OnBitmapRenderFailed onBitmapRenderFailed) Decodes a sampled Bitmap object from a given url, using the specified measures to calculate image downsample if needed.
static void	decodeBitmapFromUrl(java.lang.String url, int inSampleSize, OnBitmapRendered onBitmapRendered, OnBitmapRenderFailed onBitmapRenderFailed) Decodes a sampled Bitmap object from a given url, using the inSampleSize specified.
static void	decodeBitmapFromUrl(java.lang.String url, OnBitmapRendered onBitmapRendered, OnBitmapRenderFailed onBitmapRenderFailed) Decodes a Bitmap object from a given url, at its original dimensions.
static EpicBitmapCache	getCache() Gets the instance of the current EpicBitmapCache object being used as cache.
static void	initDiskCache(android.content.Context context) Initializes disk caches.
static void	setCache(EpicBitmapCache epicBitmapCache) Sets EpicBitmapCache object to use as cache.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getCache

public static EpicBitmapCache getCache()

Gets the instance of the current EpicBitmapCache object being used as cache.

Returns:

Cache in use.

setCache

public static void setCache(EpicBitmapCache epicBitmapCache)

Sets EpicBitmapCache object to use as cache.

Parameters:

epicBitmapCache - Cache to use by renderer

decodeBitmapFromResource

public static android.graphics.Bitmap decodeBitmapFromResource(android.content.res.Resources res,
                                                               int resId,
                                                               int reqWidth,
                                                               int reqHeight)

Decodes a sampled Bitmap object from a given app resource, using the specified measures to calculate image downsample if needed. Downsample rate is auto-increased if bitmap rendering causes an OutOfMemoryError.

Important Note: This method is synchronous and can cause UI Thread to freeze, use decodeBitmapFromResource(Resources, int, int, int, OnBitmapRendered, OnBitmapRenderFailed) instead for an asynchronous solution.

Parameters:

res - Resources package. You can get default resources package using ContextThemeWrapper.getResources() inside an activity or Context.getResources() outside if a Context is available.

resId - App resource id. Could be either the pure integer value, or the Android resource name (R.drawable.img_name).

reqWidth - Required width of the view where the Bitmap should fit. This parameter doesn't affect image aspect ratio, it's only used to calculate the inSampleSize of the image in case a downsample is required.

reqHeight - Required height of the view where the Bitmap should fit. This parameter doesn't affect image aspect ratio, it's only used to calculate the inSampleSize of the image in case a downsample is required.

Returns:

Decoded Bitmap object, ready to use on any View or code.

decodeBitmapFromResource

public static android.graphics.Bitmap decodeBitmapFromResource(android.content.res.Resources res,
                                                               int resId,
                                                               int inSampleSize)

Decodes a sampled Bitmap object from a given app resource, using the inSampleSize specified.

Important Note: This method is synchronous and can cause UI Thread to freeze, use decodeBitmapFromResource(Resources, int, int, OnBitmapRendered, OnBitmapRenderFailed) instead for an asynchronous solution.

Parameters:

res - Resources package. You can get default resources package using ContextThemeWrapper.getResources() inside an activity or Context.getResources() outside if a Context is available.

resId - App resource id. Could be either the pure integer value, or the Android resource name (R.drawable.img_name).

inSampleSize - Determines how many times image resolution is divided to lower memory usage. Image aspect ratio is not affected by this parameter, just its resolution / quality is lowered.

Returns:

Decoded Bitmap object, ready to use on any View or code.

decodeBitmapFromResource

public static android.graphics.Bitmap decodeBitmapFromResource(android.content.res.Resources res,
                                                               int resId)

Decodes a Bitmap object from a given app resource, at its original dimensions.

Important Note: This method is synchronous and can cause UI Thread to freeze, use decodeBitmapFromResource(Resources, int, OnBitmapRendered, OnBitmapRenderFailed) instead for an asynchronous solution.

Parameters:

res - Resources package. You can get default resources package using ContextThemeWrapper.getResources() inside an activity or Context.getResources() outside if a Context is available.

resId - App resource id. Could be either the pure integer value, or the Android resource name (R.drawable.img_name).

Returns:

Decoded Bitmap object, ready to use on any View or code.

decodeBitmapFromFile

public static android.graphics.Bitmap decodeBitmapFromFile(java.lang.String path,
                                                           int reqWidth,
                                                           int reqHeight)

Decodes a Bitmap object from a given file, using the specified measures to calculate image downsample if needed. Downsample rate is auto-increased if bitmap rendering causes an OutOfMemoryError.

Important Note: This method is synchronous and can cause UI Thread to freeze, use decodeBitmapFromFile(String, int, int, OnBitmapRendered, OnBitmapRenderFailed) instead for an asynchronous solution.

Parameters:

path - Physical path of File in the device storage.

reqWidth - Required width of the view where the Bitmap should fit. This parameter doesn't affect image aspect ratio, it's only used to calculate the inSampleSize of the image in case a downsample is required.

reqHeight - Required height of the view where the Bitmap should fit. This parameter doesn't affect image aspect ratio, it's only used to calculate the inSampleSize of the image in case a downsample is required.

Returns:

Decoded Bitmap object, ready to use on any View or code.

decodeBitmapFromFile

public static android.graphics.Bitmap decodeBitmapFromFile(java.lang.String path,
                                                           int inSampleSize)

Decodes a sampled Bitmap object from a given file, using the inSampleSize specified.

Important Note: This method is synchronous and can cause UI Thread to freeze, use decodeBitmapFromFile(String, int, OnBitmapRendered, OnBitmapRenderFailed) instead for an asynchronous solution.

Parameters:

path - Physical path of File in the device storage.

inSampleSize - Determines how many times image resolution is divided to lower memory usage. Image aspect ratio is not affected by this parameter, just its resolution / quality is lowered.

Returns:

Decoded Bitmap object, ready to use on any View or code.

decodeBitmapFromFile

public static android.graphics.Bitmap decodeBitmapFromFile(java.lang.String path)

Decodes a Bitmap object from a given file, at its original dimensions.

Important Note: This method is synchronous and can cause UI Thread to freeze, use decodeBitmapFromFile(String, OnBitmapRendered, OnBitmapRenderFailed) instead for an asynchronous solution.

Parameters:

path - Physical path of File in the device storage.

Returns:

Decoded Bitmap object, ready to use on any View or code.

decodeBitmapFromResource

public static void decodeBitmapFromResource(android.content.res.Resources res,
                                            int resId,
                                            int reqWidth,
                                            int reqHeight,
                                            OnBitmapRendered onBitmapRendered,
                                            OnBitmapRenderFailed onBitmapRenderFailed)

Decodes a sampled Bitmap object from a given app resource asynchronously, using the specified measures to calculate image downsample if needed. Downsample rate is auto-increased if bitmap rendering causes an OutOfMemoryError.

Parameters:

res - Resources package. You can get default resources package using ContextThemeWrapper.getResources() inside an activity or Context.getResources() outside if a Context is available.

resId - App resource id. Could be either the pure integer value, or the Android resource name (R.drawable.img_name).

reqWidth - Required width of the view where the Bitmap should fit. This parameter doesn't affect image aspect ratio, it's only used to calculate the inSampleSize of the image in case a downsample is required.

reqHeight - Required height of the view where the Bitmap should fit. This parameter doesn't affect image aspect ratio, it's only used to calculate the inSampleSize of the image in case a downsample is required.

onBitmapRendered - Overwrite this callback to retrieve Bitmap object rendered once it's ready and perform any other actions needed.

onBitmapRenderFailed - Overwrite this callback to perform actions when Bitmap object fails to render. Can be null.

decodeBitmapFromResource

public static void decodeBitmapFromResource(android.content.res.Resources res,
                                            int resId,
                                            int inSampleSize,
                                            OnBitmapRendered onBitmapRendered,
                                            OnBitmapRenderFailed onBitmapRenderFailed)

Decodes a sampled Bitmap object from a given app resource asynchronously, using the inSampleSize specified. Downsample rate is auto-increased if bitmap rendering causes an OutOfMemoryError.

Parameters:

res - Resources package. You can get default resources package using ContextThemeWrapper.getResources() inside an activity or Context.getResources() outside if a Context is available.

resId - App resource id. Could be either the pure integer value, or the Android resource name (R.drawable.img_name).

inSampleSize - Determines how many times image resolution is divided to lower memory usage. Image aspect ratio is not affected by this parameter, just its resolution / quality is lowered.

onBitmapRendered - Overwrite this callback to retrieve Bitmap object rendered once it's ready and perform any other actions needed.

onBitmapRenderFailed - Overwrite this callback to perform actions when Bitmap object fails to render. Can be null.

decodeBitmapFromResource

public static void decodeBitmapFromResource(android.content.res.Resources res,
                                            int resId,
                                            OnBitmapRendered onBitmapRendered,
                                            OnBitmapRenderFailed onBitmapRenderFailed)

Decodes a Bitmap object from a given app resource asynchronously, at its original dimensions. Downsample rate is auto-increased if bitmap rendering causes an OutOfMemoryError.

Parameters:

res - Resources package. You can get default resources package using ContextThemeWrapper.getResources() inside an activity or Context.getResources() outside if a Context is available.

resId - App resource id. Could be either the pure integer value, or the Android resource name (R.drawable.img_name).

onBitmapRendered - Overwrite this callback to retrieve Bitmap object rendered once it's ready and perform any other actions needed.

onBitmapRenderFailed - Overwrite this callback to perform actions when Bitmap object fails to render. Can be null.

decodeBitmapFromFile

public static void decodeBitmapFromFile(java.lang.String path,
                                        int reqWidth,
                                        int reqHeight,
                                        OnBitmapRendered onBitmapRendered,
                                        OnBitmapRenderFailed onBitmapRenderFailed)

Decodes a sampled Bitmap object from a given file asynchronously, using the specified measures to calculate image downsample if needed. Downsample rate is auto-increased if bitmap rendering causes an OutOfMemoryError.

Permissions: If file is outside app's own folders, this method requires the app using the library to get permission android.permissions.READ_EXTERNAL_STORAGE in order to work. If permission android.permissions.WRITE_EXTERNAL_STORAGE is granted, READ_EXTERNAL_STORAGE permission is also granted automatically.

Parameters:

path - Physical path of File in the device storage.

reqWidth - Required width of the view where the Bitmap should fit. This parameter doesn't affect image aspect ratio, it's only used to calculate the inSampleSize of the image in case a downsample is required.

reqHeight - Required height of the view where the Bitmap should fit. This parameter doesn't affect image aspect ratio, it's only used to calculate the inSampleSize of the image in case a downsample is required.

onBitmapRendered - Overwrite this callback to retrieve Bitmap object rendered once it's ready and perform any other actions needed.

onBitmapRenderFailed - Overwrite this callback to perform actions when Bitmap object fails to render. Can be null.

decodeBitmapFromFile

public static void decodeBitmapFromFile(java.lang.String path,
                                        int inSampleSize,
                                        OnBitmapRendered onBitmapRendered,
                                        OnBitmapRenderFailed onBitmapRenderFailed)

Decodes a sampled Bitmap object from a given file asynchronously, using the inSampleSize specified. Downsample rate is auto-increased if bitmap rendering causes an OutOfMemoryError.

Permissions: If file is outside app's own folders, this method requires the app using the library to get permission android.permissions.READ_EXTERNAL_STORAGE in order to work. If permission android.permissions.WRITE_EXTERNAL_STORAGE is granted, READ_EXTERNAL_STORAGE permission is also granted automatically.

Parameters:

path - Physical path of File in the device storage.

inSampleSize - Determines how many times image resolution is divided to lower memory usage. Image aspect ratio is not affected by this parameter, just its resolution / quality is lowered.

onBitmapRendered - Overwrite this callback to retrieve Bitmap object rendered once it's ready and perform any other actions needed.

onBitmapRenderFailed - Overwrite this callback to perform actions when Bitmap object fails to render. Can be null.

decodeBitmapFromFile

public static void decodeBitmapFromFile(java.lang.String path,
                                        OnBitmapRendered onBitmapRendered,
                                        OnBitmapRenderFailed onBitmapRenderFailed)

Decodes a Bitmap object from a given file asynchronously, at its original dimensions. Downsample rate is auto-increased if bitmap rendering causes an OutOfMemoryError.

Permissions: If file is outside app's own folders, this method requires the app using the library to get permission android.permissions.READ_EXTERNAL_STORAGE in order to work. If permission android.permissions.WRITE_EXTERNAL_STORAGE is granted, READ_EXTERNAL_STORAGE permission is also granted automatically.

Parameters:

path - Physical path of File in the device storage.

onBitmapRendered - Overwrite this callback to retrieve Bitmap object rendered once it's ready and perform any other actions needed.

onBitmapRenderFailed - Overwrite this callback to perform actions when Bitmap object fails to render. Can be null.

decodeBitmapFromUrl

public static void decodeBitmapFromUrl(java.lang.String url,
                                       int reqWidth,
                                       int reqHeight,
                                       OnBitmapRendered onBitmapRendered,
                                       OnBitmapRenderFailed onBitmapRenderFailed)

Decodes a sampled Bitmap object from a given url, using the specified measures to calculate image downsample if needed.

Permissions: This method requires the app using the library to use permission android.permissions.INTERNET in order to work.

Parameters:

url - Image resource URL (e.g. http://www.website.com/image.png)

reqWidth - Required width of the view where the Bitmap should fit. This parameter doesn't affect image aspect ratio, it's only used to calculate the inSampleSize of the image in case a downsample is required.

reqHeight - Required height of the view where the Bitmap should fit. This parameter doesn't affect image aspect ratio, it's only used to calculate the inSampleSize of the image in case a downsample is required.

onBitmapRendered - Overwrite this callback to retrieve Bitmap object rendered once it's ready and perform any other actions needed.

onBitmapRenderFailed - Overwrite this callback to perform actions when Bitmap object fails to render. Can be null.

decodeBitmapFromUrl

public static void decodeBitmapFromUrl(java.lang.String url,
                                       int inSampleSize,
                                       OnBitmapRendered onBitmapRendered,
                                       OnBitmapRenderFailed onBitmapRenderFailed)

Decodes a sampled Bitmap object from a given url, using the inSampleSize specified.

Permissions: This method requires the app using the library to use permission android.permissions.INTERNET in order to work.

Parameters:

url - Image resource URL (e.g. http://www.website.com/image.png)

inSampleSize - Determines how many times image resolution is divided to lower memory usage. Image aspect ratio is not affected by this parameter, just its resolution / quality is lowered.

onBitmapRendered - Overwrite this callback to retrieve Bitmap object rendered once it's ready and perform any other actions needed.

onBitmapRenderFailed - Overwrite this callback to perform actions when Bitmap object fails to render. Can be null.

decodeBitmapFromUrl

public static void decodeBitmapFromUrl(java.lang.String url,
                                       OnBitmapRendered onBitmapRendered,
                                       OnBitmapRenderFailed onBitmapRenderFailed)

Decodes a Bitmap object from a given url, at its original dimensions.

Permissions: This method requires the app using the library to use permission android.permissions.INTERNET in order to work.

Parameters:

url - Image resource URL (e.g. http://www.website.com/image.png)

onBitmapRendered - Overwrite this callback to retrieve Bitmap object rendered once it's ready and perform any other actions needed.

onBitmapRenderFailed - Overwrite this callback to perform actions when Bitmap object fails to render. Can be null.

initDiskCache

public static void initDiskCache(android.content.Context context)

Initializes disk caches.

Important Note: Until an alternative is found, this method must be called (Just once for whole app life cycle, and in any time) before using any render method, other way, Bitmap objects rendered won't be stored on disk cache, just in memory cache.

Parameters:

context - Context from where lib is being called. This is used to get application's cache dir for disk cache.

calculateInSampleSize

public static int calculateInSampleSize(android.graphics.BitmapFactory.Options options,
                                        int reqWidth,
                                        int reqHeight)

Calculates downsample rate, if needed, for an image depending of width and height it should fit on.

Parameters:

options - BitmapFactory.Options object containing image info.

reqWidth - Required width of the view where the Bitmap should fit.

reqHeight - Required height of the view where the Bitmap should fit.

Returns:

int representing inSampleSize, a.k.a. the number of times image resolution is divided to lower memory usage.

See Also:

Google conventions for calculate inSampleSize.