zadvorsky / three.bas

THREE.JS Buffer Animation System

THREE.BAS

THREE Buffer Animation System is an extension for THREE.js. It simplifies the workflow of extending the built-in THREE.js materials to include animation logic in the vertex shader. For an overview of this approach, check out this tutorial series.

The standard way of animating objects in THREE.js is to change the values of position, rotation and scale on the CPU and upload the results to the GPU as a transformation matrix. As the number of objects increases, the volume of data sent to the GPU each frame becomes a bottleneck. THREE.BAS works around this issue by storing additional information on the GPU when the geometry is created (using attributes). The animation state is then determined in the vertex shader based on a small number of uniform values.

The two building blocks of this approach are THREE.BufferGeometry and THREE.ShaderMaterial. The geometry is used to store additional attributes. The material contains animation logic inside the shader. In stead of using ShaderMaterial directly, THREE.BAS provides subclasses that duplicate the behavior of THREE.js materials (MeshBasic, MeshPhong and MeshStandard) and an API to inject (animation) logic in specific locations. This way you can make full use of features such as lighting.

While this approach is more cumbersome to work with, it provides a significant performance boost both on desktop and mobile. It has been used in award winning projects such as Cavalier Challenge and DS Signature Art.

See examples, documentation and the wiki for more information.

There is also a tutorial here that goes through the basics of vertex shaders, and the approach of BAS. Part 4 in particular focusses on using this extension.

Compatibility

Because this project uses some Three.js internals, it may (or may not) break with each new Three.js release. The aim is to support the current release, so please let me know if anything breaks!

Note: After version 3.0.0, three.js is treated as a peerDependency to mitigate some issues with multiple threejs versions in certrain build setups. You will need to manually install a version of THREE in your project (tested with r141).

Usage

Include dist/bas.js or dist/bas.min.js in your project. An npm package is also available:

$ npm install three-bas

ES6 imports

import * as BAS from 'three-bas'
// or
import {
  PrefabBufferGeometry,
  StandardAnimationMaterial,
  // etc
} from 'three-bas'

Development

This project relies or npm and rollup for building the source.

Run $ npm install to install dependencies and npm run dev to start building. Then run any local server, like live-server in the same directory to serve the examples.

three.bas's Issues

Can prefab cast a shadow on other prefabs within one mesh?

If it can, does the shader animation have any limitations with these shadows?
I assume it cannot, but in case, here is my test codepen. Can't get it working.
The pink box is a different mesh.

Is it possible for Three.bas to work with the [react-three-fiber] package?

Any insight from anyone trying to use the Three.bas altered versions of THREE.BufferGeometry and THREE.ShaderMaterial with [react-three-fiber]?

https://www.npmjs.com/package/@react-three/fiber

document link is invalid

How can I custom texture in Three.bas

Three.bas effect is amazing,How can I custom texture in Three.bas

Most examples are broken on the examples site

I'm getting errors on almost all examples. Complaints about OrbitControls; probably a simple fix:

root.js:56 Uncaught TypeError: THREE.OrbitControls is not a constructor
    at THREERoot.createOrbitControls (root.js:56:21)
    at new THREERoot (root.js:52:39)
    at init (main.js:4:14)

Prefab Geometry vs. Instanced Geometry

Hello 😄 What is the difference between prefab geometry in three-bas and instanced geometry in three.js itself? They seem kinda similar to me, but I'm probably missing something basic.

I'm sorry, I know this is not really an issue. Is there a better place to ask these questions? Thank you ❤️

Text Animations

Found this examples:
https://codepen.io/collection/ABaxyy/

Realy love it! But seems it works only with old versions of Three.js and Three.bas libs. Is anyware working examples with newer libs versions?

Feature request: Add LambertAnimationMaterial

First of all, thanks for this amazing library!
It's my understanding that LambertMaterial is slightly more performant than PhongMaterial. Would be nice to add it as default material to the library :-)

PhongAnimationMaterial fragmentSpecular incorrect order?

i'm having trouble controlling phong material's specular properties in the fragment shader using fragmentSpecular and material.specularShininess. I think the issue is that the fragmentSpecular block is injected after the lighting is calculated and only gets applied to the environment map

here is a demo of the current way it works, where the changes to material don't seem to be applied (expecting to see pink color) - https://codepen.io/clindsey/pen/GadgqZ

here's a demo where i've changed the ordering - https://codepen.io/clindsey/pen/oRdWKE

here's a PR for a potential fix - #35

Is this library still supported?

Seems that it doesnt work anymore with newer versions of Three.js

this.BufferIndices is not a function

When trying to run the Image-transition example, I get this error
from bas.min.js.

Anyone knows the cause??

Shadows and defines (bug?)

I am using StandardAnimationMaterial and found a problem with shadows BAS.Utils.createDepthAnimationMaterial and BAS.Utils.createDistanceAnimationMaterial.
Custom #define are not added to the shader, so i get the error: 'SIZE' : undeclared identifier.

If I fix the "defines", by adding them manually, i get 'objectNormal' : undeclared identifier. I know objectNormal is a Three.js shader chunk, so I suppose it's not imported for some reason.

NOTE: this only happens if i add a light and set castShadow to true and the renderer has shadowMap enabled. Otherwise everything works fine (but no shadows!).

how to set color or texture on LambertAnimationMaterial

Is there any way to set color or texture in LambertAnimationMaterial and other AnimationMaterial, if i set color in it, it shows that 'color' is not a property of this material.

So all the materials' color is white or it could be change in some different ways

Help

Hello~, I was your fan when I saw your project on CODEPEN，and I really like your project examples/timeline_1.
Here I have an idea that I want to change the material's color of the third row to green in your project examples/timeline_1. but my ability is limited and I have failed to change the color.
Can you help me achieve it? Thank you very much.

Documentation site is down.

could you please update the version on npm

BAS in npm is not the new version and if I use three.js r96, it will cause an error.
So please update BAS on npm.
Thanks.

Have geometry always face the camera?

I'm attempting to modify the cavalier speed particles demo to have them always face the camera but am having difficulty.

I was told I had to convert the units to camera-space (https://www.gamedeveloper.com/programming/building-an-advanced-particle-system). However I'm not really certain how to do that and then transform back.

      vertexPosition: [
        // calculate a time based on the uniform time and the offset of each prefab
        'float tProgress = mod((uTime + (aOffset * uDuration)), uDuration) / uDuration;',

        // convert to camera space here and do something? <--
        'vec4 myTransform = vec4(position, 1.) * modelViewMatrix ;',

        // scale the z axis based on the uniform speed scale
        'transformed.z *= uScale;',
        // translate between start and end position based on progress
        'transformed += mix(aStartPosition, aEndPosition, tProgress);',
      ],

fragment rendering errors for PrefabBufferGeometry + PhongAnimationMaterial

I'm not able to get PrefabBufferGeometry instances with PhongAnimationMaterial to render correctly when they're overlapping on the screen. It seems like the fragment shader isn't able to correctly depth sort. I'm updating transformed in the vertex shader to position the object but the fragment shader isn't picking up on it. Is there a way to correct this, or should I just stick to ToonAnimationMaterial like in the examples?

example code - https://codepen.io/clindsey/pen/ydeaKx

Updates for latest r125

I'm curious if anyone is working on updates to three.bas for the latest three.js release, which at time of writing is r125?

I'm just a casual observer at this point, evaluating the cool tech you have here for a project currently in development. I don't mean to add any pressure.

bufferUVs vs bufferUvs - typo?

These two classes have the same method but they're spelled slightly differently -

http://three-bas-examples.surge.sh/docs/gen/THREE.BAS.PrefabBufferGeometry.html#bufferUvs__anchor

http://three-bas-examples.surge.sh/docs/gen/THREE.BAS.ModelBufferGeometry.html#bufferUVs__anchor

Compatibility with bufferGeometry

Hello, i believe the compatibility with the geometry is broken.
I tried to use ModelBufferGeometry with three.TextGeometry but ModelBufferGeometry is using the three.geometry.face's property which doesn't exist anymore.
I believe threejs moved their geometries to buffergeometry

useful link: https://stackoverflow.com/questions/42141438/access-to-faces-in-buffergeometry

Hope to hearing from you soon !

How do I change an opacity for each prefab using a PrefabBufferGeometry?

What if I have a PrefabBufferGeometry, but I just wanna change the opacity for each prefab separately in the fragment shader using StandardAnimationMaterial, is it possible to achieve this? Or after PrefabBufferGeometry creation it is considered as one object?

Spline look-ahead rotation.

Hi, I was wondering if the spline functions could be used to look 10 points (or something like this) ahead and use that to rotate the PrefabGeometry towards that point, so you could have things like rockets flying along splines, oriented to the direction of the spline.

Shader compatibility regarding past examples and newer versions of THREE

Apologies if this is not the correct place for this.

I'm trying to replicate this in my project so it can be modified to fit my needs:
https://codepen.io/zadvorsky/pen/PNXbGo

Each of the objects from the classes instantiate fine as expected however I get the following error when using the following version of THREE:
https://cdnjs.cloudflare.com/ajax/libs/three.js/110/three.min.js

three.module.js:17071 THREE.WebGLProgram: shader error:  0 35715 false gl.getProgramInfoLog invalid shaders�  THREE.WebGLShader: gl.getShaderInfoLog() fragment
ERROR: 0:261: 'vUv' : undeclared identifier
ERROR: 0:261: 'texture' : no matching overloaded function found
ERROR: 0:261: '=' : dimension mismatch
ERROR: 0:261: '=' : cannot convert from 'const mediump float' to 'highp 4-component vector of float'
ERROR: 0:262: 'mapTexelToLinear' : no matching overloaded function found
ERROR: 0:262: '=' : dimension mismatch
ERROR: 0:262: 'assign' : cannot convert from 'const mediump float' to 'highp 4-component vector of float'

I would like to know if this is a known/expected issue or could it maybe be the way I'm implementing it?

I also get an alternative error when attempting to add the Slide to my scene and switching to:
https://cdnjs.cloudflare.com/ajax/libs/three.js/r75/three.min.js

THREE.Object3D.add: object not an instance of THREE.Object3D.

I don't believe the latter issue to be as important as it's most likely an issue with my implementation however I would greatly appreciate any information or advice on why either of these errors occur as I'm a little stumped.

Issue working with gsap 3

I'm trying to implement the Image Transition example in a React Codesandbox using GSAP 3 and installing all packages from NPM.

After converting the appropriate chunks of code per their migration guidelines, I'm unable to get any images to render.

Here is the link to the sandbox - https://codesandbox.io/s/amazing-lamport-k5sce?file=/src/imageTransition.tsx

Any ideas what's wrong?

The Slide.setImage call was erroring at first, so I updated the code to do this after reading through this issue:

var texture = new THREE.Texture();
...
material.uniforms.map.value = texture;
material.map = texture;

add webpack 2 instructions

webpack 2 is pretty popular, but it requires some extra setup, we should add instructions for it. Let's figure that out here and I'll create a PR for an updated readme.md

---

webpack 2

install dependencies

these are the base libraries, plus a loader that can handle the .glsl files

npm install --save three three-bas shader-loader

webpack config

configure the loader for .glsl files, and shim THREE

{
  module: {
    rules: [
      { // handle shaders files
        test: /\.(glsl|vs|fs)$/,
        loader: 'shader-loader'
      }
    ]
  },
  plugins: [ // three.bas expects THREE to be globally available
    new webpack.ProvidePlugin({
      'THREE': 'three'
    })
  ]
}

importing

three and bas don't have a default export, so remember to correctly reference them

import * as THREE from 'three'
import * as BAS from 'three-bas'

toJSON() not working with AnimationMaterials

As far as I can tell using builtin toJSON() is not working.

I have a mesh using a BAS.StandardAnimationMaterial() and get the following error if I try to mesh.toJSON():

Uncaught TypeError: Cannot read property 'isTexture' of null

Can you support the latest version?Version 109

Can you support the latest version?Version 109

three.js r84 support

basic_transform example not working with r84

DepthAnimationMaterial: Problem casting shadows taking alpha into account

Hi @zadvorsky,

I have a little problem using the DepthAnimationMaterial. I have a scene with a bunch of instanced grass tufts using the InstancedPrefabBufferGeometry. I want them tufts to cast shadows taking their map's alpha into account. See the image below for an example based on MeshStandardMaterial and MeshDepthMaterial:

Example

In order to achieve this, I have to pass the following parameters to the MeshDepthMaterial in THREE.JS

{ depthPacking: THREE.RGBADepthPacking, map: MY_TEXTURE, alphaTest: 0.5, }.

adding these properties to my DepthAnimationMaterial has no effect besides that shadows disappear. I have the feeling I am missing something fundamental, so I would be very thankful if you could point me in the right direction :)

Thanks in advance and keep up the work!

add working GPGPU example

it looks like there was an example branch for GPGPU, but it's incomplete

it would be great if there was a working example for GPGPU

Using a normalMap uniformValue along with ToonAnimationMaterial causes shader compile error

I am trying to create a BAS.ToonAnimationMaterial() using a normalMap in the uniformValues like so:

const material = new BAS.ToonAnimationMaterial({
			name: 'Material',
			extensions: {
				derivates: true
			},
			uniformValues: {
				normalMap: SOME TEXTURE HERE
			}
		})

This causes the following error:

ERROR: 0:784: 'GL_OES_standard_derivatives' : extension is disabled

As soon as I remove the normalMap property from the uniformValues everything works as expected.

Does this project still iterating ?

Can three.bas be used to achieve gltf model animation?

In my project, I want to achieve a scene in which many vehicles are driving. Now I hava a glb car model , Can three.bas be used to achieve this scene ?

hello,how to change triangle to square

fragmentMap vUv is always == 0.0?

I've run into a weird / and hard to debug issue with BasicAnimationMaterial and options.fragmentMap where the vUv is always a = vec2(0.0, 0.0).

Here's some pseudo code of the setup abstracted from my general code:

var options = {uniformValues: {}}
options.uniformValues.map = new THREE.TextureLoader().load('assets/textures/uv_grid.jpg');

options.fragmentMap = [
	'if (vUv.x == 0.0) {',
	'diffuseColor = vec4(1.0, 0.0, 0.0, 1.0);',
	'} else {',
	'vec4 texelColor1 = texture2D(map, vUv);',
	'diffuseColor *= texelColor1;',
'}'
];

my geometry is instanced like this:

let planeTest = new THREE.PlaneGeometry(0.5, 0.5, 1.0, 1.0);
		let geometry = new BAS.PrefabBufferGeometry(planeTest, 6);
		geometry.computeVertexNormals();
		geometry.bufferUvs();
let material = new BAS.BasicAnimationMaterial(materialOptions);

I've confirmed that vUv never changes from 0.0, 0.0 because i see 6 completely red planes rendered.

Any idea / suggestions of how to debug this?

Material.shading removed from Three.js r87

Hey. Thanks for this extension, it's insanely useful :)

I found an issue with Three r87 and PhongAnimationMaterial (but i suppose it's the same with all materials).
Basically r87 removed the shading property of Material. It has been replaced by flatShading and it's a boolean. https://threejs.org/docs/#api/materials/Material

This is from the log of r87: https://github.com/mrdoob/three.js/releases/tag/r87
Replaced .shading with .flatShading. #11724 #11727 #11730 94aedce #11982 (@WestLangley and @dhritzkiv)

So now if you do new THREE.BAS.PhongAnimationMaterial({ shading: THREE.FlatShading }) you get an error.