Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

@thi.ng/porter-duff

0.1.20 • Public • Published

porter-duff

npm version npm downloads Twitter Follow

This project is part of the @thi.ng/umbrella monorepo.

About

Porter-Duff operators for packed ints & float-array alpha compositing.

This package provides all 13 fundamental Porter-Duff compositing / blending operators, and utilities to pre/post-multiply alpha. All operators are available for packed ARGB/ABGR 32bit packed ints or RGBA float vectors.

References

Status

STABLE - used in production

Related packages

Installation

yarn add @thi.ng/porter-duff
// ES module
<script type="module" src="https://unpkg.com/@thi.ng/porter-duff?module" crossorigin></script>
 
// UMD
<script src="https://unpkg.com/@thi.ng/porter-duff/lib/index.umd.js" crossorigin></script>

Package sizes (gzipped, pre-treeshake): ESM: 998 bytes / CJS: 1.16 KB / UMD: 1.13 KB

Dependencies

Usage examples

Several demos in this repo's /examples directory are using this package.

A selection:

Screenshot Description Live demo Source
Pixel buffer manipulations Demo Source
Port-Duff image compositing / alpha blending Demo Source

API

Generated API docs

Basic usage

import * as pd from "@thi.ng/porter-duff";
 
// packed int version (premultiplied ARGB)
pd.SRC_OVER_I(0x80800000, 0xcc0cc00)
 
// automatically premultiply inputs & post-multiply result
pd.porterDuffPInt(pd.SRC_OVER_I, 0x80ff0000, 0xcc00ff00);
 
// the above is same as:
pd.postmultiplyInt(
    pd.SRC_OVER_I(
        pd.premultiplyInt(0x80ff0000),
        pd.premultiplyInt(0xcc00ff00)
    )
)
 
// premultiplied float version [R,G,B,A]
pd.SRC_OVER_F([1, 0, 0, 0.5], [0, 1, 0, 0.8]);

Operators

Integer operators are suffixed with _I, float versions with _F. Consult above diagram for expected results.

  • CLEAR
  • SRC
  • DEST
  • SRC_OVER
  • DEST_OVER
  • SRC_IN
  • DEST_IN
  • SRC_OUT
  • DEST_OUT
  • SRC_ATOP
  • DEST_ATOP
  • XOR
  • PLUS

Custom operators

New operators (e.g. for blend modes) can be easily defined via porterDuff / porterDuffInt. Both functions take 2 function arguments to extract blend coefficients from the src & dest colors:

// coefficient functions take the normalized alpha values
// of both colors as arguments, but unused here...
const customOp = porterDuffInt(() => -0.5, () => 1);

custom operator

The following coefficient functions are included by default (and are used by all standard operators):

  • ZERO => 0
  • ONE => 1
  • A => alpha of src color
  • B => alpha of dest color
  • ONE_MINUS_A => 1 - alpha of src color
  • ONE_MINUS_B => 1 - alpha of dest color

Additional operators / modifiers

The following modifiers are also discussed in the original Porter-Duff paper (linked above).

  • darken / darkenInt
  • dissolve / dissolveInt
  • opacity / opacityInt

Pre/post-multiplied colors

All Porter-Duff operators expect colors with pre-multiplied alpha. Premultiplication is also recommended for transparent WebGL textures (especially when using mipmaps). For that purpose the following helpers might be useful:

  • premultiply / premultiplyInt
  • postmultiply / postmultiplyInt
  • isPremultiplied / isPremultipliedInt

Furthermore, existing PD operators can be wrapped with automatic pre/post-multiplies using porterDuffP / porterDuffPInt (see example above).

Note: HTML Canvas ImageData is using non-premultiplied colors.

Authors

Karsten Schmidt

License

© 2018 - 2020 Karsten Schmidt // Apache Software License 2.0

Install

npm i @thi.ng/porter-duff

DownloadsWeekly Downloads

190

Version

0.1.20

License

Apache-2.0

Unpacked Size

69.6 kB

Total Files

18

Last publish

Collaborators

  • avatar