npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

three-extend-material

v1.0.0

Published

Plugin for extending built-in materials, instances of ShaderMaterial and built-in materials as well as shader objects of `onBeforeCompile`.

Downloads

25

Readme

Extending Materials

Plugin for extending built-in materials, instances of ShaderMaterial and built-in materials as well as shader objects of onBeforeCompile.

Demo: Creating new materials based on MeshStandardMaterial and custom depth material for shadows

THREE.extendMaterial( constructor|material|shaderMaterial [, options])

For patching in onBeforeCompile: THREE.patchShader( object [, options])


const myMaterial = THREE.extendMaterial(THREE.MeshPhongMaterial, {

	// Will be prepended to vertex and fragment code
	header: 'varying vec3 vEye;',

	// Will be prepended to vertex code
	headerVertex: '',

	// Will be prepended to fragment code
	headerFragment: '',

	// If desired, the material class to create can be defined such as RawShaderMaterial or ShaderMaterial, by
	// default in order to seamlessly work with in-built features the CustomMaterial class provided by this
	// plugin is used which is a slightly extended ShaderMaterial.
	// class: THREE.ShaderMaterial,

	// Insert code lines by hinting at a existing
	vertex: {

		// Inserts the line after #include <fog_vertex>

		'#include <fog_vertex>': 'vEye = normalize(cameraPosition - w.xyz);',

		// Replaces a line (@ prefix) inside of the project_vertex include

		'project_vertex': {
			'@vec4 mvPosition = modelViewMatrix * vec4( transformed, 1.0 );': 'vec4 mvPosition = modelViewMatrix * vec4( transformed * 0.5, 1.0 );'
		}
	},
	fragment: {
		'#include <envmap_fragment>': 'diffuseColor.rgb += pow(dot(vNormal, vEye), 3.0);'
	},


	// Properties to apply to the new THREE.ShaderMaterial
	material: {
		skinning: true
	},


	// Uniforms (will be applied to existing or added) as value or uniform object
	uniforms: {

		// Use a value directly, uniform object will be created for or ..
		diffuse: new THREE.Color(0xffffff),

		// ... provide the uniform object, by declaring a shared: true property and such you can ensure
		// the object will be shared across materials rather than cloned.
		emissive: {
			shared: true, // This uniform can be shared across all materials it gets assigned to, sharing the value
			mixed : true, // When creating a material with/from a template this will be passed through
			linked: true, // To share them when used as template but not when extending them further, this ensures you don’t have
						  // to sync. uniforms from your original material with the depth material for shadows for example (see Demo)
			value: new THREE.Color('pink')
		}
	}

});

Patching shader code

Code can be appended, prepended and replaced by providing some indicating line code (typically includes like above) and a prefix to define if the code should be appended, prepended to the hinted line or replace it.

Prefix | Insertion --- | --- none | append ? | prepend @ | replace

Templates

When creating a material variation such as a depth material and the previous patched code should be applied too, defining a template will apply all previous patches again. This is useful when creating alternative versions, for example a custom depth material that also respects custom vertex transformations.

For example, you extended MeshStandardMaterial with some vertex distortions to add wind motion.

const depthMaterial = THREE.extendMaterial( THREE.MeshDepthMaterial, {
	
	template: myMaterial
	
});

Release notes

Fix

  • Adapted compatibility with 127+ releases (es6 classes)
  • Module version added

Version 2

  • A new THREE.CustomMaterial which stays more compatible to the in-built materials when extending those
  • class property in options to use another material class than ShaderMaterial (e.g CustomMaterial)
  • mixed property in uniforms to pass them from templates
  • linked property in uniforms to share them when used as template but not when extending them, this ensures you don't have to sync. uniforms from your original material with the depth material for shadows for example
  • Compatibility with RawShaderMaterial
  • Uniforms can be given now as wrapper-object or their value
  • Cloning materials now respects shared uniforms
  • Alias THREE.extendMaterial as shorter alternative to THREE.ShaderMaterial.extend
  • Fixed compatibility with minified THREE bundles
  • Templates (applying of previous code patches and inheriting properties)
  • Sharing of uniform wrapper by defining a shared {shared: true, value: .. } boolean in a uniform object
  • vertexHeader, fragmentHeader, vertexEnd, fragmentEnd added wich will only add the given string to the corresponding part while the "End" ones will add the string at the end of the main function
  • Constants (defines) which are a boolean false will get removed as they are mainly used with #ifdef in THREE what causes a false positive for this condition
  • customDepthMaterial and customDistanceMaterial can be also defined on materials now, so it doesn't need to be assigned for every new mesh with this material
  • Uniforms are reduced to what has been defined at least with null and necessary pairs (for example normalMapScale when normalMap is defined), this saves a large amount of uniforms that aren't used
  • Lights uniforms are now shared instead cloned for every material (it's a huge set), internally THREE assigns the value for all equally anyway