Novelty Plastic Moustache

    @thi.ng/porter-duff
    TypeScript icon, indicating that this package has built-in type declarations

    2.1.6 • 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

    Search or submit any issues for this package

    Related packages

    Installation

    yarn add @thi.ng/porter-duff

    ES module import:

    <script type="module" src="https://cdn.skypack.dev/@thi.ng/porter-duff"></script>

    Skypack documentation

    For Node.js REPL:

    # with flag only for < v16
    node --experimental-repl-await
    
    > const porterDuff = await import("@thi.ng/porter-duff");
    

    Package sizes (gzipped, pre-treeshake): ESM: 1.01 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

    If this project contributes to an academic publication, please cite it as:

    @misc{thing-porter-duff,
      title = "@thi.ng/porter-duff",
      author = "Karsten Schmidt",
      note = "https://thi.ng/porter-duff",
      year = 2018
    }

    License

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

    Install

    npm i @thi.ng/porter-duff

    DownloadsWeekly Downloads

    182

    Version

    2.1.6

    License

    Apache-2.0

    Unpacked Size

    47.3 kB

    Total Files

    14

    Last publish

    Collaborators

    • thi.ng