pixijs / picture

A plugin that includes a sprite renderer that reduces border artifacts and 3 blend mode implementations for WebGL
MIT License
67 stars 20 forks source link

@pixi/picture - PixiJS Picture Kit

Compatible with PixiJS 7.2.0 and up. No guarantee for earlier versions!

Usage

import * as PIXI from 'pixi.js';
import {Sprite, getBlendFilter} from '@pixi/picture';
// hacked sprite or tilingSprite
const sprite = new Sprite();
sprite.blendMode = PIXI.BLEND_MODES.OVERLAY;
// for other kind of elements
const graphics = new PIXI.Graphics();
graphics.filters = [getBlendFilter(PIXI.BLEND_MODES.OVERLAY)];

Tutorials

Known bugs

Blend-modes emulated through filters

Allows to use blendModes that are not available in pure webgl implementation, such as PIXI.BLEND_MODES.OVERLAY.

Please, don't add children to sprite if you use those blendModes.

Use import { Sprite } from '@pixi/picture' instead of PIXI.Sprite (do not use Sprite.from). You can re-export it instead of pixi sprite if you use custom pixi build.

Overlay example

Logic: if sprite has special blendMode, push corresponding filter getBlendFilter(blendMode), if area is too small (<1px), dont draw at all.

If you want to use this with any components - just look in the source of Sprite how its done.

Assigning a filter to component directly container.filters = [getBlendFilter(blendMode)] should work too.

To be fixed: At the moment this implementation is a bit worse than v4, it uses extra pass for filter.

Heavenly filter feature

Enables backdropSampler uniform in filters, works only if you render stage to renderTexture or you have a filter somewhere in parents.

Sample DisplacementFilter takes everything from container and applies it as a displacement texture on backdrop.

Note: Currently, if there is a filter that uses backdrop on the element - all filters use resolution from backdrop, you cannot set custom resolution for them!

Displacement example

Pixelate example

Drawing from main framebuffer

Since version 3.0.1, pixi-picture finally does not need filter above it. However, that comes with a problem: WebGL main framebuffer is flipped by Y.

You have to use backdropSampler_flipY uniform in your blend filters to transform Y coord in case renderTexture was flipped.

If specified useContextAlpha: false in renderer creation parameters, main framebuffer is RGB and not RGBA, its not possible to copyTex it, you will see corresponding warning message in the console.

When using MaskFilter with maskBefore=true, input is automatically flipped by Y. This operation is not needed if your base filter does not care about flipping Y, for example BlurFilter or ColorMatrixFilter. In this case, you can specify maskFilter.safeFlipY=true, that will turn off extra flipping.

Vanilla JS, UMD build

All pixiJS v6 plugins has special umd build suited for vanilla. Navigate pixi-picture npm package, take dist/pixi-picture.umd.js file.

<script src='lib/pixi.js'></script>
<script src='lib/pixi-picture.umd.js'></script>
let sprite = new PIXI.picture.Sprite();

Previous versions

For PixiJS v5 and prior see README pixi-v5 branch, or just use npm package pixi-picture For PixiJS v6 see pixi-v6 branch , npm version 3.0.6

How to build

pnpm install
pnpm run build