koral--/android-gif-drawable — 9.7k Stars

Topics

#android #animated-gifs #drawable #gif #hacktoberfest

Language breakdown

Java 58.3%

C 40.6%

Assembly 0.9%

CMake 0.2%

▸ Files click to expand

README

====================

Views and Drawable for animated GIFs in Android.

Overview

Bundled GIFLib via JNI is used to render frames. This way should be more efficient than WebView or Movie classes.

Javadoc

Setup

Gradle (Android Studio)

Insert the following dependency to build.gradle file of your project.

dependencies {
    implementation 'pl.droidsonroids.gif:android-gif-drawable:1.2.32'
}

Note that Maven central repository should be defined eg. in top-level build.gradle like this:

buildscript {
    repositories {
        mavenCentral()
    }
}
allprojects {
    repositories {
        mavenCentral()
    }
}

Gradle, snapshot repository

Current development builds (build from dev branch) are published to OSS snapshot repository. To use them, specify repository URL in repositories block:

repositories {
    mavenCentral()
    maven { url "https://oss.sonatype.org/content/repositories/snapshots" }
}
dependencies {
    implementation 'pl.droidsonroids.gif:android-gif-drawable:1.2.+'
}

Maven dependency

<dependency>
    <groupId>pl.droidsonroids.gif</groupId>
    <artifactId>android-gif-drawable</artifactId>
    <version>insert latest version here</version>
    <type>aar</type>
</dependency>

Eclipse

See Sample eclipse project with setup instructions.

Download

Latest release downloads

Requirements

Android 4.2+ (API level 17+)
for GifTextureView hardware-accelerated rendering
for GifTexImage2D OpenGL ES 2.0+

Building from source

Android NDK needed to compile native sources

Usage

Sample project

See sample directory. Sample project is under construction. Not all features are covered yet.

From XML

The simplest way is to use GifImageView (or GifImageButton) like a normal ImageView:

<pl.droidsonroids.gif.GifImageView
    android:layoutwidth="matchparent"
    android:layoutheight="matchparent"
    android:src="@drawable/src_anim"
    android:background="@drawable/bg_anim"
    />

If drawables declared by android:src and/or android:background are GIF files then they will be automatically recognized as GifDrawables and animated. If given drawable is not a GIF then mentioned Views work like plain ImageView and ImageButton.

GifTextView allows you to use GIFs as compound drawables and background.

<pl.droidsonroids.gif.GifTextView     android:layoutwidth="matchparent"     android:layoutheight="matchparent"     android:drawableTop="@drawable/left_anim"     android:drawableStart="@drawable/left_anim"     android:background="@drawable/bg_anim"     />

From Java code

GifImageView, GifImageButton and GifTextView have also hooks for setters implemented. So animated GIFs can be set by calling setImageResource(int resId) and setBackgroundResource(int resId)

GifDrawable can be constructed directly from various sources:

//asset file
GifDrawable gifFromAssets = new GifDrawable( getAssets(), "anim.gif" );
		
//resource (drawable or raw)
GifDrawable gifFromResource = new GifDrawable( getResources(), R.drawable.anim );
		
//Uri
ContentResolver contentResolver = ... //can be null for file:// Uris
GifDrawable gifFromUri = new GifDrawable( contentResolver, gifUri );
//byte array byte[] rawGifBytes = ... GifDrawable gifFromBytes = new GifDrawable( rawGifBytes ); 		 //FileDescriptor FileDescriptor fd = new RandomAccessFile( "/path/anim.gif", "r" ).getFD(); GifDrawable gifFromFd = new GifDrawable( fd ); 		 //file path GifDrawable gifFromPath = new GifDrawable( "/path/anim.gif" ); 		 //file File gifFile = new File(getFilesDir(),"anim.gif"); GifDrawable gifFromFile = new GifDrawable(gifFile); 		 //AssetFileDescriptor AssetFileDescriptor afd = getAssets().openFd( "anim.gif" ); GifDrawable gifFromAfd = new GifDrawable( afd ); 				 //InputStream (it must support marking) InputStream sourceIs = ... BufferedInputStream bis = new BufferedInputStream( sourceIs, GIF_LENGTH ); GifDrawable gifFromStream = new GifDrawable( bis ); 		 //direct ByteBuffer ByteBuffer rawGifBytes = ... GifDrawable gifFromBytes = new GifDrawable( rawGifBytes );

When you pass an InputStream, FileDescriptor or AssetFileDescriptor, the library takes ownership of it and closes it, so you don't need to (and must not) close it yourself. InputStreams are closed automatically in the finalizer if the GifDrawable is no longer needed; calling recycle()

 will also close the underlying input source.
Note that all input sources need to have ability to rewind to the beginning. It is required to correctly play animated GIFs  (where animation is repeatable) since subsequent frames are decoded on demand from source.
Animation control

GifDrawable implements an Animatable and MediaPlayerControl

 so you can use its methods and more:

stop() - stops the animation, can be called from any thread

start() - starts the animation, can be called from any thread

isRunning() - returns whether animation is currently running or not

reset() - rewinds the animation, does not restart stopped one

setSpeed(float factor) - sets new animation speed factor, eg. passing 2.0f will double the animation speed

seekTo(int position) - seeks animation (within current loop) to given position (in milliseconds)

getDuration() - returns duration of one loop of the animation

getCurrentPosition() - returns elapsed time from the beginning of a current loop of animation


Using MediaPlayerControl
Standard controls for a MediaPlayer (like in VideoView) can be used to control GIF animation and show its current progress.

Just set GifDrawable as MediaPlayer on your MediaController like this: <pre><code class="lang-java">@Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); GifImageButton gib = new GifImageButton(this); setContentView(gib); gib.setImageResource(R.drawable.sample); final MediaController mc = new MediaController(this); mc.setMediaPlayer((GifDrawable) gib.getDrawable()); mc.setAnchorView(gib); gib.setOnClickListener(new OnClickListener() { @Override public void onClick(View v) { mc.show(); } }); }</code></pre>


Retrieving GIF metadata

getLoopCount() - returns a loop count as defined in NETSCAPE 2.0 extension

getNumberOfFrames() - returns number of frames (at least 1)

getComment() - returns comment text (null if GIF has no comment)

getFrameByteCount() - returns minimum number of bytes that can be used to store pixels of the single frame

getAllocationByteCount() - returns size (in bytes) of the allocated memory used to store pixels of given GifDrawable

getInputSourceByteCount() - returns length (in bytes) of the backing input data

toString() - returns human readable information about image size and number of frames (intended for debugging purpose)

`Associating single` GifDrawable `instance with multiple` View`s`

Normally single GifDrawable instance associated with multiple Views will animate only on the last one. To solve that create MultiCallback instance, add Views to it and set callback for given drawable, e.g.: <pre><code class="lang-java">MultiCallback multiCallback = new MultiCallback();


imageView.setImageDrawable(gifDrawable); multiCallback.addView(imageView);
anotherImageView.setImageDrawable(gifDrawable); multiCallback.addView(anotherImageView);
gifDrawable.setCallback(multiCallback);</code></pre>

Note that if you change a drawable of e.g. ImageView, the callback will be removed from the previous drawable. Thereafter, you have to reassign callback or the same GifDrawable instance will stop animating. See #480 for more information.


Advanced

recycle() - provided to speed up freeing memory (like in android.graphics.Bitmap)

isRecycled() - checks whether drawable is recycled

getError() - returns last error details


Upgrading from 1.2.15
Minimum SDK version changed
Minimum API level is now 17 (Android 4.2).

armeabi

 (arm v5 and v6) is no longer supported.
Upgrading from 1.2.8
Minimum SDK version changed
Minimum API level is now 14 (Android 4.0).
Upgrading from 1.2.3
Meaningful only if consumer proguard rules (bundled with library) are not used (they are used by default by Gradle).

Proguard rule has changed to -keep public class pl.droidsonroids.gif.GifIOException{(int, java.lang.String);}


Upgrading from 1.1.17
1.1.17 is the last version supporting API level 8 (Froyo). Starting from 1.2.0 minimum API level is 9 (Gingerbread).
Upgrading from 1.1.13
Handling of several edge cases has been changed:

GifDrawable#getNumberOfFrames() now returns 0 when GifDrawable is recycled

Information included in result of GifDrawable#toString() when GifDrawable is recycled now contains zeroes only


Upgrading from 1.1.10
It is recommended (but not required) to call

LibraryLoader.initialize() before using GifDrawable. Context

 is needed in some cases
when native libraries cannot be extracted normally. See ReLinker
for more details. 
If

LibraryLoader.initialize() was not called and normal library loading fails, Context

 will be tried to be retrieved in fall back way which may not always work.
Upgrading from 1.1.9

int parameter loopNumber has been added to AnimationListener#onAnimationCompleted()

.
Upgrading from 1.1.8
Proguard configuration not needed
Proguard configuration is now bundled with the library, you don't need to specify it yourself.
Upgrading from 1.1.3

src XML attribute in GifTextureView has been renamed to gifSource

 to avoid possible conflicts with other libraries.
Upgrading from 1.0.x
Proguard configuration update
Proguard configuration has changed to:
<pre><code class="lang-">-keep public class pl.droidsonroids.gif.GifIOException{&lt;init&gt;(int);}
-keep class pl.droidsonroids.gif.GifInfoHandle{&lt;init&gt;(long,int,int,int);}</code></pre>
Drawable recycling behavior change

GifDrawable now uses android.graphics.Bitmap

 as frame buffer. Trying to access pixels (including drawing)
 of recycled

GifDrawable will cause IllegalStateException like in Bitmap`.

Minimum SDK version changed

Minimum API level is now 8 (Android 2.2).

Rendering moved to background thread

Rendering is performed in background thread running independently from main thread so animation is running even if drawable is not drawn. However rendering is not running if drawable is not visible, see #setVisible()). That method can be used to control drawable visibility in cases when it is not already handled by Android framework.