repository·master·Indexed 42 days ago
https://github.com/themadcreator/giflerA lightweight JavaScript library (v0.3.0) for animating GIFs directly onto an HTML5 canvas. It uses XHR for loading and omggif for decoding to provide a high-performance rendering pipeline with support for custom rendering logic and frame-by-frame control.
Gifler is a library designed to animate GIFs within a HTML5 canvas. It handles the following lifecycle steps:
omggif library.To animate a GIF using Gifler, include the gifler.min.js script and call the gifler() function with the path to your GIF file. Chain the .animate() method to specify the CSS selector of the canvas element where the animation should be rendered.
Note: The target element must be a <canvas> element.
<canvas class="example"></canvas>
<script src="gifler.min.js"></script>
<script>
gifler('image.gif').animate('.example');
</script>The get(callback) method returns a promise that fulfills with an Animator instance. This allows you to bypass the high-level Gif methods and interact directly with the animation engine.
Once you have the Animator instance, you can call animator.animateInCanvas(canvas) to start the animation manually.
Returns:
A promise that resolves with an Animator instance.
gifler('path/to/your.gif').get().then(function(animator) {
// The animator is in an unstarted state
animator.animateInCanvas(document.querySelector('canvas'));
});The animate(selector) method on a Gif instance draws each frame of the loaded GIF into a <canvas> element, matching the visual behavior of an <img> tag.
Arguments:
selector: A <canvas> element or a CSS query selector string for a <canvas> element.Returns: A promise that resolves when the animation starts.
gifler('path/to/your.gif').then(function(gif) {
gif.animate('#my-canvas');
});The frames(selector, onDrawFrame, setDimensions) method provides complete control over how each frame is drawn into the canvas context. This is useful if you want to apply effects or custom logic during the rendering loop.
Arguments:
selector: A <canvas> element or a CSS query selector string for a <canvas> element.onDrawFrame: A callback function invoked when each frame is drawn. The callback receives (ctx, frame, i) where ctx is the canvas 2D context, frame is the frame object, and i is the frame index.setDimensions (Optional): If true, the canvas's width/height will be set to the dimensions of the loaded GIF. Defaults to false.Returns: A promise that resolves when the animation starts.
gifler('path/to/your.gif').then(function(gif) {
gif.frames('#my-canvas', function(ctx, frame, i) {
// Custom drawing logic
ctx.drawImage(frame.buffer, frame.x, frame.y);
}, true);
});The Animator instance (obtained via gif.get()) provides low-level control over the animation loop.
Methods:
start(): Starts the GIF animation loop.stop(): Stops the GIF animation loop.reset(): Resets the animation loop to the first frame (does not stop the animation).running(): Returns a boolean indicating whether the animation is currently running.animateInCanvas(canvas, setDimensions): Prepares the canvas and starts the animation. To change how frames are drawn, override animator.onDrawFrame or animator.onFrame before calling this method. setDimensions defaults to true.Overriding Callbacks:
onDrawFrame: A function to define how a frame is drawn. If not set, it defaults to ctx.drawImage(frame.buffer, frame.x, frame.y).onFrame: A function to handle lazy construction of canvas buffers and frame disposal.gifler('path/to/your.gif').get().then(function(animator) {
animator.start();
// ... later
animator.stop();
animator.reset();
});The gifler(url) function is the main entrypoint. It performs an XHR request to load a GIF file from the provided url and returns a Gif instance. The Gif instance is used to control the animation and rendering process.
Arguments:
url: A string representing the URL to the .gif file.Returns:
A Gif instance object.
Note: The Gif instance is initialized via a promise that resolves once the GIF data is loaded and decoded.
const gifler = require('gifler');
gifler('path/to/your.gif').then(function(gif) {
// Use the gif instance here
});A static utility method on the Gif class used to resolve a selector into a valid <canvas> element.
Arguments:
selector: Either a string (CSS query selector) or a direct <canvas> element.Returns:
The <canvas> element.
Throws:
An Error if the selector is not a string pointing to a <canvas> or is not a <canvas> element itself.