pex-shaders

Shader library and manipulation for PEX.

Installation

npm install pex-shaders

Usage

import { pipeline, parser } from "pex-shaders";
import createContext from "pex-context";

const ctx = createContext();

const defines = [
  "USE_BASE_COLOR_TEXTURE",
  // ...
];

const program = {
  vert: parser.build(ctx, pipeline.material.vert, defines),
  frag: parser.replaceStrings(
    parser.build(ctx, pipeline.material.frag, defines),
    { directionalLights: 3 }
  ),
};

API

• All GLSL shaders are by default written using GLSL 1. They also provide support for GLSL 3 where possible using the __VERSION__ standard macro, #define for built-ins keywords and parser.build(ctx, src).
• PBR material fragment shader specifies 3 named outputs for gl_FragData: outColor, outEmissiveColor and outNormal.
• Defines and extensions can also be prepended with parser.build(ctx, src, defines, extensions)
• Pipeline shaders have hooks for easy string replace:
  • #define HOOK_VERT_DECLARATIONS_END
  • #define HOOK_VERT_END
  • #define HOOK_FRAG_DECLARATIONS_END
  • #define HOOK_FRAG_END
• PBR material has additional hooks:
  • #define HOOK_VERT_BEFORE_TRANSFORM
  • #define HOOK_FRAG_BEFORE_TEXTURES
  • #define HOOK_FRAG_BEFORE_LIGHTING
  • #define HOOK_FRAG_AFTER_LIGHTING

Modules

pex-shaders

parser

chunks

pipeline

postProcessing

reflectionProbe

skybox

pex-shaders

• pex-shaders
  • .chunks : chunks
  • .pipeline : pipeline
  • .postProcessing : postProcessing
  • .reflectionProbe : reflectionProbe
  • .skybox : skybox
  • .parser : parser
  • .toneMap : object

pex-shaders.chunks : chunks

Various shader chunks to be inserted in main shaders

Kind: static property of pex-shaders

pex-shaders.pipeline : pipeline

Main shaders

Kind: static property of pex-shaders

pex-shaders.postProcessing : postProcessing

Post-processing shaders that operate on fullscreen

Kind: static property of pex-shaders

pex-shaders.reflectionProbe : reflectionProbe

Reflection probes specific shaders

Kind: static property of pex-shaders

pex-shaders.skybox : skybox

Skybox specific shaders

Kind: static property of pex-shaders

pex-shaders.parser : parser

Shader string manipulation helpers

Kind: static property of pex-shaders

pex-shaders.toneMap : object

Re-export tone mapping functions

Kind: static property of pex-shaders See: https://github.com/dmnsgn/glsl-tone-map

parser

• parser
  • .GLSL3
  • .formatExtensions([extensions]) ⇒ string
  • .formatDefines([defines]) ⇒ string
  • .build(ctx, src, [defines], [extensions]) ⇒ string
  • .patchES300(src, stage) ⇒ string
  • .replaceStrings(src, options) ⇒ string
  • .getFormattedError(error, options) ⇒ string

parser.GLSL3

GLSL 3 preprocessor version string

Kind: static constant of parser

parser.formatExtensions([extensions]) ⇒ string

Format an object of extension names as key and extension behaviosr (enable/require/warn/disable) as value

Kind: static method of parser

Param	Type	Default
[extensions]	object	{}

parser.formatDefines([defines]) ⇒ string

Format an array of define keys

Kind: static method of parser

Param	Type	Default
[defines]	Array.<string>	[]

parser.build(ctx, src, [defines], [extensions]) ⇒ string

Add version string and format a list of defines for a shader source

Kind: static method of parser

Param	Type	Default
ctx	ctx
src	string
[defines]	Array.<string>	[]
[extensions]	object	{}

parser.patchES300(src, stage) ⇒ string

Monkey patch a shader string for ES300 by replacing builtin keywords and un-necessary extensions, and adding the version preprocessor string

Kind: static method of parser

Param	Type
src	string
stage	"vertex" | "fragment"

parser.replaceStrings(src, options) ⇒ string

Unroll loops (looped preceded by "#pragma unroll_loop") for lights and replace their constant iterators

Kind: static method of parser

Param	Type
src	string
options	object

parser.getFormattedError(error, options) ⇒ string

Get a formatted error pointing at the issue line

Kind: static method of parser

Param	Type
error	Error
options	Object

chunks

• chunks
  • .output : object
  • .math : object
  • .encodeDecode : string
  • .luma : string
  • .luminance : string
  • .average : string
  • .lightAmbient : string
  • .lightDirectional : string
  • .lightPoint : string
  • .lightSpot : string
  • .lightArea : string
  • .shadowing : string
  • .pcf : object
  • .pcss : object
  • .brdf : string
  • .direct : string
  • .indirect : string
  • .envMapEquirect : string
  • .octMap : string
  • .octMapUvToDir : string
  • .irradiance : string
  • .textureCoordinates : string
  • .baseColor : string
  • .emissiveColor : string
  • .normal : string
  • .normalPerturb : string
  • .metallicRoughness : string
  • .specular : string
  • .specularGlossiness : string
  • .clearCoat : string
  • .sheenColor : string
  • .transmission : string
  • .alpha : string
  • .ambientOcclusion : string
  • .depthRead : string
  • .depthPosition : string
  • .depthUnpack : string
  • .depthPack : string
  • .fog : string
  • .fxaa : string
  • .filmGrain : string
  • .lut : string
  • .vignette : string
  • .colorCorrection : string
  • .filmGrain : string
  • .fog : string
  • .fxaa : string
  • .noise : object

chunks.output : object

Kind: static property of chunks

chunks.math : object

Kind: static property of chunks

chunks.encodeDecode : string

Kind: static property of chunks

chunks.luma : string

Kind: static property of chunks

chunks.luminance : string

Kind: static property of chunks

chunks.average : string

Kind: static property of chunks

chunks.lightAmbient : string

Kind: static property of chunks

chunks.lightDirectional : string

Kind: static property of chunks

chunks.lightPoint : string

Kind: static property of chunks

chunks.lightSpot : string

Kind: static property of chunks

chunks.lightArea : string

Kind: static property of chunks

chunks.shadowing : string

Kind: static property of chunks

chunks.pcf : object

Kind: static property of chunks

chunks.pcss : object

Kind: static property of chunks

chunks.brdf : string

Kind: static property of chunks

chunks.direct : string

Kind: static property of chunks

chunks.indirect : string

Kind: static property of chunks

chunks.envMapEquirect : string

Kind: static property of chunks

chunks.octMap : string

Kind: static property of chunks

chunks.octMapUvToDir : string

Kind: static property of chunks

chunks.irradiance : string

Kind: static property of chunks

chunks.textureCoordinates : string

Kind: static property of chunks

chunks.baseColor : string

Kind: static property of chunks

chunks.emissiveColor : string

Kind: static property of chunks

chunks.normal : string

Kind: static property of chunks

chunks.normalPerturb : string

Kind: static property of chunks

chunks.metallicRoughness : string

Kind: static property of chunks

chunks.specular : string

Kind: static property of chunks

chunks.specularGlossiness : string

Kind: static property of chunks

chunks.clearCoat : string

Kind: static property of chunks

chunks.sheenColor : string

Kind: static property of chunks

chunks.transmission : string

Kind: static property of chunks

chunks.alpha : string

Kind: static property of chunks

chunks.ambientOcclusion : string

Kind: static property of chunks

chunks.depthRead : string

Kind: static property of chunks

chunks.depthPosition : string

Kind: static property of chunks

chunks.depthUnpack : string

Kind: static property of chunks

chunks.depthPack : string

Kind: static property of chunks

chunks.fog : string

Kind: static property of chunks

chunks.fxaa : string

Kind: static property of chunks

chunks.filmGrain : string

Kind: static property of chunks

chunks.lut : string

Kind: static property of chunks

chunks.vignette : string

Kind: static property of chunks

chunks.colorCorrection : string

Color Correction

https://github.com/CesiumGS/cesium/blob/master/Source/Shaders/Builtin/Functions

Kind: static property of chunks

chunks.filmGrain : string

Film Grain

Reference Implementations:

• https://devlog-martinsh.blogspot.com/2013/05/image-imperfections-and-film-grain-post.html
• https://www.shadertoy.com/view/4sSXDW

Kind: static property of chunks

chunks.fog : string

Fog

Adapted from from Iñigo Quilez article: https://iquilezles.org/articles/fog/

Kind: static property of chunks

chunks.fxaa : string

FXAA

Paper:

• https://developer.download.nvidia.com/assets/gamedev/files/sdk/11/FXAA_WhitePaper.pdf

Reference Implementations:

• https://blog.simonrodriguez.fr/articles/2016/07/implementing_fxaa.html
• https://gist.github.com/kosua20/0c506b81b3812ac900048059d2383126

Updates: Damien Seguin (2023-10)

Kind: static property of chunks

chunks.noise : object

Reference Implementation: https://github.com/stegu/webgl-noise

Copyright (C) 2011 by Ashima Arts (Simplex noise) Copyright (C) 2011-2016 by Stefan Gustavson (Classic noise and others)

Kind: static constant of chunks

pipeline

• pipeline
  • .blit : object
    • .frag : string
    • .vert : string
  • .depthPass : object
    • .frag : string
    • .vert : string
  • .depthPrePass : object
    • .frag : string
  • .standard : object
    • .frag : string
    • .vert : string
  • .basic : object
    • .frag : string
    • .vert : string
  • .line : object
    • .frag : string
    • .vert : string
  • .overlay : object
    • .frag : string
    • .vert : string
  • .helper : object
    • .frag : string
    • .vert : string
  • .error : object
    • .frag : string
    • .vert : string

pipeline.blit : object

Kind: static constant of pipeline

• .blit : object
  • .frag : string
  • .vert : string

blit.frag : string

Kind: static property of blit

blit.vert : string

Kind: static property of blit

pipeline.depthPass : object

Kind: static constant of pipeline

• .depthPass : object
  • .frag : string
  • .vert : string

depthPass.frag : string

Kind: static property of depthPass

depthPass.vert : string

Kind: static property of depthPass

pipeline.depthPrePass : object

Kind: static constant of pipeline

depthPrePass.frag : string

Kind: static property of depthPrePass

pipeline.standard : object

Kind: static constant of pipeline

• .standard : object
  • .frag : string
  • .vert : string

standard.frag : string

Kind: static property of standard

standard.vert : string

Kind: static property of standard

pipeline.basic : object

Kind: static constant of pipeline

• .basic : object
  • .frag : string
  • .vert : string

basic.frag : string

Kind: static property of basic

basic.vert : string

Kind: static property of basic

pipeline.line : object

Kind: static constant of pipeline

• .line : object
  • .frag : string
  • .vert : string

line.frag : string

Kind: static property of line

line.vert : string

Kind: static property of line

pipeline.overlay : object

Kind: static constant of pipeline

• .overlay : object
  • .frag : string
  • .vert : string

overlay.frag : string

Kind: static property of overlay

overlay.vert : string

Kind: static property of overlay

pipeline.helper : object

Kind: static constant of pipeline

• .helper : object
  • .frag : string
  • .vert : string

helper.frag : string

Kind: static property of helper

helper.vert : string

Kind: static property of helper

pipeline.error : object

Kind: static constant of pipeline

• .error : object
  • .frag : string
  • .vert : string

error.frag : string

Kind: static property of error

error.vert : string

Kind: static property of error

postProcessing

• postProcessing
  • .bilateralBlur : object
    • .frag : string
  • .dof : object
    • .frag : string
  • .downsample : object
    • .frag : string
  • .postProcessing : object
    • .frag : string
    • .vert : string
  • .sao : object
    • .frag : string
  • .gtao : object
    • .frag : string
  • .ssaoMix : object
    • .frag : string
  • .threshold : object
    • .frag : string
  • .upsample : object
    • .frag : string

postProcessing.bilateralBlur : object

Kind: static constant of postProcessing

bilateralBlur.frag : string

Kind: static property of bilateralBlur

postProcessing.dof : object

Kind: static constant of postProcessing

dof.frag : string

DoF (Depth of Field)

Based on:

• "Bokeh depth of field in a single pass", Dennis Gustafsson: https://blog.voxagon.se/2018/05/04/bokeh-depth-of-field-in-single-pass.html
• "GLSL depth of field with bokeh v2.4", Martins Upitis: https://devlog-martinsh.blogspot.com/2011/12/glsl-depth-of-field-with-bokeh-v24.html

Kind: static property of dof

postProcessing.downsample : object

Kind: static constant of postProcessing

downsample.frag : string

Downsample

Reference Implementation: https://github.com/keijiro/KinoBloom

Kind: static property of downsample

postProcessing.postProcessing : object

Kind: static constant of postProcessing

• .postProcessing : object
  • .frag : string
  • .vert : string

postProcessing.frag : string

Kind: static property of postProcessing

postProcessing.vert : string

Kind: static property of postProcessing

postProcessing.sao : object

Kind: static constant of postProcessing

sao.frag : string

SAO (Scalable Ambient Obscurance)

Paper: https://research.nvidia.com/sites/default/files/pubs/2012-06_Scalable-Ambient-Obscurance/McGuire12SAO.pdf (https://casual-effects.com/research/McGuire2012SAO/index.html)

Reference Implementation: https://gist.github.com/transitive-bullshit/6770311

Updates: Marcin Ignac (2017-05-08) and Damien Seguin (2023-10)

Kind: static property of sao

postProcessing.gtao : object

Kind: static constant of postProcessing

gtao.frag : string

GTAO (Ground Truth)

Paper: https://www.activision.com/cdn/research/Practical_Real_Time_Strategies_for_Accurate_Indirect_Occlusion_NEW%20VERSION_COLOR.pdf

Reference Implementation: https://github.com/GameTechDev/XeGTAO/blob/master/Source/Rendering/Shaders/XeGTAO.hlsli

Updates: Damien Seguin (2023-10)

Kind: static property of gtao

postProcessing.ssaoMix : object

Kind: static constant of postProcessing

ssaoMix.frag : string

SSAO mix

Kind: static property of ssaoMix

postProcessing.threshold : object

Kind: static constant of postProcessing

threshold.frag : string

Kind: static property of threshold

postProcessing.upsample : object

Kind: static constant of postProcessing

upsample.frag : string

Upsample

Reference Implementation: https://github.com/keijiro/KinoBloom

Kind: static property of upsample

reflectionProbe

• reflectionProbe
  • .blitToOctMapAtlas : object
    • .frag : string
  • .convolveOctMapAtlasToOctMap : object
    • .frag : string
  • .cubemapToOctMap : object
    • .frag : string
  • .downsampleFromOctMapAtlas : object
    • .frag : string
  • .prefilterFromOctMapAtlas : object
    • .frag : string

reflectionProbe.blitToOctMapAtlas : object

Kind: static constant of reflectionProbe

blitToOctMapAtlas.frag : string

Kind: static property of blitToOctMapAtlas

reflectionProbe.convolveOctMapAtlasToOctMap : object

Kind: static constant of reflectionProbe

convolveOctMapAtlasToOctMap.frag : string

Kind: static property of convolveOctMapAtlasToOctMap

reflectionProbe.cubemapToOctMap : object

Kind: static constant of reflectionProbe

cubemapToOctMap.frag : string

Kind: static property of cubemapToOctMap

reflectionProbe.downsampleFromOctMapAtlas : object

Kind: static constant of reflectionProbe

downsampleFromOctMapAtlas.frag : string

Kind: static property of downsampleFromOctMapAtlas

reflectionProbe.prefilterFromOctMapAtlas : object

Kind: static constant of reflectionProbe

prefilterFromOctMapAtlas.frag : string

Kind: static property of prefilterFromOctMapAtlas

skybox

• skybox
  • .skybox : object
    • .frag : string
    • .vert : string
  • .skyEnvMap : object
    • .frag : string
    • .vert : string

skybox.skybox : object

Kind: static constant of skybox

• .skybox : object
  • .frag : string
  • .vert : string

skybox.frag : string

Kind: static property of skybox

skybox.vert : string

Skybox

Based on http://gamedev.stackexchange.com/questions/60313/implementing-a-skybox-with-glsl-version-330

Kind: static property of skybox

skybox.skyEnvMap : object

Kind: static constant of skybox

• .skyEnvMap : object
  • .frag : string
  • .vert : string

skyEnvMap.frag : string

Sky

Based on "A Practical Analytic Model for Daylight" aka The Preetham Model, the de facto standard analytic skydome model

Paper: https://www.researchgate.net/publication/220720443_A_Practical_Analytic_Model_for_Daylight

Reference Implementation:

• First implemented by Simon Wallner http://www.simonwallner.at/projects/atmospheric-scattering
• Improved by Martins Upitis http://blenderartists.org/forum/showthread.php?245954-preethams-sky-impementation-HDR
• Three.js integration by zz85 http://twitter.com/blurspline

Updates: Marcin Ignac http://twitter.com/marcinignac (2015-09) and Damien Seguin (2023-10)

Kind: static property of skyEnvMap

skyEnvMap.vert : string

Kind: static property of skyEnvMap

License

MIT. See license file.