pixijs / gif

Plugin to support playback of animated GIF images in PixiJS.

PixiJS — The HTML5 Creation Engine

This project aims to provide a fast, lightweight 2D library that works across all devices. The PixiJS renderer allows everyone to enjoy the power of hardware acceleration without prior knowledge of WebGL. Also, it's fast. Really fast.

If you want to keep up to date with the latest PixiJS news then feel free to follow us on Twitter @PixiJS and we will keep you posted! You can also check back on our site as any breakthroughs will be posted up there too!

We are now a part of the Open Collective and with your support you can help us make PixiJS even better. To make a donation, simply click the button below and we'll love you forever!

What to Use PixiJS for and When to Use It

PixiJS is a rendering library that will allow you to create rich, interactive graphics and cross-platform applications and games without having to dive into the WebGL API or deal with browser and device compatibility.

PixiJS supports WebGPU with fallback support for WebGL. As a library, PixiJS is a fantastic tool for authoring interactive content. Use it for your graphics-rich, interactive websites, applications, and HTML5 games. Out-of-the-box, cross-platform compatibility and graceful degradation mean you have less work to do and more fun doing it! If you want to create polished and refined experiences relatively quickly without delving into dense, low-level code, all while avoiding the headaches of browser inconsistencies, then sprinkle your next project with some PixiJS magic!

Boost your development and feel free to use your imagination!

Current features

• WebGL renderer (with automatic smart batching, allowing for REALLY fast performance)
• WebGPU renderer (new to the latest browsers!)
• Canvas renderer (Fastest in town!)
• Full scene graph
• Super easy to use API (similar to the flash display list API)
• Support for texture atlases
• Asset loader / sprite sheet loader
• Auto-detect which renderer should be used
• Full Mouse and Multi-touch Interaction
• Text
• BitmapFont text
• Multiline Text
• Render Texture
• Primitive Drawing
• Masking
• Filters
• Community-Supported Plugins
  • React
  • Spine
  • Filters
  • Animate
  • Lights
  • UI
  • Layout
  • GIF
  • And more!

Setup

It's easy to get started with PixiJS! Simply download a prebuilt build!

Alternatively, PixiJS can be installed with npm or simply using a content delivery network (CDN) URL to embed PixiJS directly on your HTML page.

NPM Install

npm install pixi.js

There is no default export. The correct way to import PixiJS is:

import * as PIXI from 'pixi.js';

CDN Install

Via jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/pixi.min.js"></script>

Or via unpkg:

<script src="https://unpkg.com/[email protected]/dist/pixi.min.js"></script>

Basic Usage Example

import { Application, Sprite, Assets } from 'pixi.js';

// The application will create a renderer using WebGL, if possible,
// with a fallback to a canvas render. It will also setup the ticker
// and the root stage PIXI.Container
const app = new Application();

// Wait for the Renderer to be available
await app.init();

// The application will create a canvas element for you that you
// can then insert into the DOM
document.body.appendChild(app.canvas);

// load the texture we need
const texture = await Assets.load('bunny.png');

// This creates a texture from a 'bunny.png' image
const bunny = new Sprite(texture);

// Setup the position of the bunny
bunny.x = app.renderer.width / 2;
bunny.y = app.renderer.height / 2;

// Rotate around the center
bunny.anchor.x = 0.5;
bunny.anchor.y = 0.5;

// Add the bunny to the scene we are building
app.stage.addChild(bunny);

// Listen for frame updates
app.ticker.add(() => {
    // each frame we spin the bunny around a bit
    bunny.rotation += 0.01;
});

Learn

• Website: Find out more about PixiJS on the official website.
• Getting Started:
  • Check out the getting started guide.
  • Also, check out @miltoncandelero's PixiJS tutorials aimed toward videogames with recipes and best practices here
• Examples: Get stuck right in and play around with PixiJS code and features right here!
• API Documentation: Get to know the PixiJS API by checking out the docs.
• Guide: Supplementary usage guides to the API Documentation here.

Demos

• Filters Demo
• Bunny Demo
• Masking Demo
• Interaction Demo
• More examples

Community

• Forums: Check out the discussions and Stackoverflow -- both friendly places to ask your PixiJS questions.
• Chat: You can join us on Discord to chat about PixiJS.

How to build

Note that for most users you don't need to build this project. If all you want is to use PixiJS, then just download one of our prebuilt releases. The only time you should need to build PixiJS is if you are developing it.

If you don't already have Node.js and NPM, go install them. Then, in the folder where you have cloned the repository, install the build dependencies using npm:

npm install

Then, to build the source, run:

npm run build

How to generate the documentation

The docs can be generated using npm:

npm run docs

Contribute

Want to be part of the PixiJS project? Great! All are welcome! We will get there quicker together :) Whether you find a bug, have a great feature request, or you fancy owning a task from the road map above, feel free to get in touch.

Make sure to read the Contributing Guide before submitting changes.

License

This content is released under the (http://opensource.org/licenses/MIT) MIT License.

gif's Issues

CANNOT READ PROPERTIES OF UNDEFINED (READING 'LINEAR')

I'm trying to use @pixijs/gif in my app but there is an issue.
when I import it:

import @pixi/gif

get this error message:

CANNOT READ PROPERTIES OF UNDEFINED (READING 'LINEAR')
TYPEERROR: CANNOT READ PROPERTIES OF UNDEFINED (READING 'LINEAR') AT EVAL (WEBPACK-INTERNAL:///./NODE_MODULES/@PIXI/GIF/DIST/PIXI-GIF.ESM.MJS:15:12094) AT ./NODE_MODULES/@PIXI/GIF/DIST/PIXI-GIF.ESM.MJS (HTTP://LOCALHOST:3000/_NEXT/STATIC/CHUNKS/SRC_COMPONENTS_CANVAS_BILLBOARDCANVAS_INDEX_TSX.JS:4362:1) AT OPTIONS.FACTORY (HTTP://LOCALHOST:3000/_NEXT/STATIC/CHUNKS/WEBPACK.JS?TS=1666530387962:688:31) AT __WEBPACK_REQUIRE__ (HTTP://LOCALHOST:3000/_NEXT/STATIC/CHUNKS/WEBPACK.JS?TS=1666530387962:37:33) AT FN (HTTP://LOCALHOST:3000/_NEXT/STATIC/CHUNKS/WEBPACK.JS?TS=1666530387962:343:21) AT EVAL (WEBPACK-INTERNAL:///./SRC/COMPONENTS/CANVAS/BILLBOARDCANVAS/INDEX.TSX:9:67) AT ./SRC/COMPONENTS/CANVAS/BILLBOARDCANVAS/INDEX.TSX (HTTP://LOCALHOST:3000/_NEXT/STATIC/CHUNKS/SRC_COMPONENTS_CANVAS_BILLBOARDCANVAS_INDEX_TSX.JS:73:1) AT OPTIONS.FACTORY (HTTP://LOCALHOST:3000/_NEXT/STATIC/CHUNKS/WEBPACK.JS?TS=1666530387962:688:31) AT __WEBPACK_REQUIRE__ (HTTP://LOCALHOST:3000/_NEXT/STATIC/CHUNKS/WEBPACK.JS?TS=1666530387962:37:33) AT FUNCTION.FN (HTTP://LOCALHOST:3000/_NEXT/STATIC/CHUNKS/WEBPACK.JS?TS=1666530387962:343:21)

TypeError: Cannot read properties of undefined (reading 'end')

Version

    "pixi.js": "^6.2.0",
    "@pixi/gif" :"1.1.3"

I used the old docu

Install the loader for handle GIF images.

import { AnimatedGIFLoader } from '@pixi/gif';
import { Loader } from '@pixi/loaders';
Loader.registerPlugin(AnimatedGIFLoader);

function loadAsset(){
  const app = new Application();
  fetch('image.gif')
      .then(res => res.arrayBuffer())
      .then(AnimatedGIF.fromBuffer)
      .then(image => app.stage.addChild(image));
}

What does this message indicate?

Some images may not be rendered correctly

Code to reproduce:

import * as PIXI from 'pixi.js';
import '@pixi/gif';

const app = new PIXI.Application();

document.body.appendChild(app.view);

const image = await PIXI.Assets.load('https://i2.mij.rip/2023/07/17/8f75a5d815120d64dbbcdc44906a975d.gif');
app.stage.addChild(image);

Probably these lines of code caused this result:

gif/src/AnimatedGIF.ts

Lines 237 to 240 in 25b3839

	if (disposalType === 2 || disposalType === 3)
	{
	context.clearRect(0, 0, canvas.width, canvas.height);
	}

"Uncaught Error: Frame index out of range" unless TARGET_FPMS is set

I'm getting an issue where unless I set TARGET_FPMS to a number, the frame index does not get set correctly and it errors out.
I suspect this is caused by the line const elapsed = this.animationSpeed * deltaTime / (settings.TARGET_FPMS as number); which if TARGET_FMPS is not set would cause elapsed to be undefined, poisoning the frame index.

I just recently switched to pixijs 7.0.0-alpha.3 and gif 2.0.0 and this error seems new to that. Looking at the code though I'm not sure why this hasn't happened before, as settings.TARGET_FPMS seems like it has been undefined for a little while at least.

The docs for 7.0.0-alpha3 state that TARGET_FPMS has a Default Value of 0.06 but in this minimal test case, I'm getting undefined for both v7 and v6.5.2

import { settings } from '@pixi/settings'
console.log(settings.TARGET_FPMS)

Anyways, hopefully this helps. If there's a right way to fix this, I'm happy to make a pull request. Otherwise, settings.TARGET_FPMS = 0.06; is a perfectly good workaround so no worries if this gets closed or something.

Using AnimatedGif.clone() should mark clones as dirty to trigger an update

Hey there,
I've noticed that cloning an AnimatedGIF and immediatly adding it to a container causes it to not be shown for a fraction of a second.

I've tried reproducing the behaviour on a StackBlitz:
https://stackblitz.com/edit/vitejs-vite-63qf4t?file=src%2Fmain.ts

I looked through the repository and if I am not mistaken it would be due to the fact that when we .clone() the AnimatedGIF ...

• dirtyis initially set to false
• updateFrameIndex has not been called yet, therefore not setting dirty = true
• when updateFrameis called it won't execute since dirty is not set to true.

Frame index out of the range

First of all, thanks for the plugin. really help me in my current project.
I'm having this issue when following the steps shown in the documentation:

I cannot figure out what's going on.
Here is an example of the code: https://codesandbox.io/s/pjijs-gif-frnug

GIF is partially rendered for some GIFs

Getting the resource.animation and adding it to the canvas for some GIFs only renders a portion of the GIF.

This renders on the canvas as

Analysing the GIF, the first frame has smaller dimensions than the overall GIF, which might be why

How to use the plugin when gif file without extension

    use(resource: LoaderResource, next: (...args: any[]) => void): void
    {
        if (resource.extension === GIF_EXTENSION)
        {
            resource.animation = AnimatedGIF.fromBuffer(resource.data);
        }
        next();
    }

gif/src/AnimatedGIFLoader.ts

Line 46 in 425290b

if (resource.extension === GIF_EXTENSION)

according to the source code, the plugin only works when resource extension is .gif,
while my gif url could be https://example.com/425290bcf without file extension

playback from percent of page loaded

I want to control the playback of a gif, where the frame corresponds to the percentage of the base page that is loaded. In essence, a loading screen. Is this possible?

when using Pixijs with transparent gif, the gif shows the old pixels (not cleaning previous)

when using Pixijs with transparent gif, the gif shows the old pixels (not cleaning previous).
see issue:

attaching transparent gif to try as well:

thank you for a great project,

FYI using latest libs.

Sean.