FarazzShaikh/three-shader-baker

🍰 Bake your Three.js shaders or materials into textures!

^THREE Shader Baker

Bake your Three.js shaders or materials into textures!

Here, ThreeJS fragment shaders are exported out as textures which are then used in Blender. This demo is real! Give it a click.

Shader Baker lets you export your Three.js shaders or materials as textures. This is useful when you want to use the same shader in other 3D software like Blender, Unity, etc. You can also use the exported textures in other Three.js shaders/materials to save on performance.

It supports both Vanilla and React!

Show Vanilla example

import { ShaderBaker, getTextureAsDataUrl } from "three-shader-baker";

const mesh = new THREE.Mesh(...)

const baker = new ShaderBaker();
const fbo = baker.bake(renderer, mesh, {
  // Optional options
  scene: scene, // Scene that the mesh is in. If provided, the current env map will be used.
  size: 1024, // Number. Size of the baked texture
  target: null // THREE.WebGLRenderTarget. If provided, the baked texture will be rendered to this target.
})

// Your resulting texture
const dataUrl = getTextureAsDataUrl(renderer, fbo.texture);

Show React example

import {
  ShaderBaker,
  useShaderBaker,
  getTextureAsDataUrl
} from "three-shader-baker/react";

function Mesh() {
  const { bake } = useShaderBaker();
  const meshRef = useRef();

  useEffect(() => {
    const fbos = bake();
    const targrtFbo = fbos[meshRef.uuid];

    // Your resulting texture
    const dataUrl = getTextureAsDataUrl(renderer, targetFbo.texture);
  }, []);

  return <mesh ref={meshRef}>...</mesh>;
}

<ShaderBaker>
  <Mesh />
</ShaderBaker>;

License

This project is licensed under the AGPL-3.0 License. See the LICENSE file for details.Please email me at farazzshaikh@gmail.com if you would like to use this library under a different license.

Installation

npm install three-shader-baker
yarn add three-shader-baker

Helpers (React only)

You can set the following helpers on THREE.Mesh.userData to control the baking process:

• __shaderBaker_isExcluded - Set this to true to exclude the mesh from baking.
• __shaderBaker_size - Set this to a number to override the size of the baked texture for this mesh. Can be used to bake different textures at different resolutions.

Gotchas

• (React only) The bake functions from const { bake } = useShaderBaker() is memoized. Make sure to pass it as a dependency in your useEffect hook otherwise it will unnecessary state updates.
• (React only) The order of priority for the size prop is as follows:
  1. __shaderBaker_size on the mesh
  2. size parameter in the bake function
  3. size prop on the <ShaderBaker /> component
• Lighting is baked from a single point of view ([0, 0, -1] looking towards [0, 0, 0]). This means specular highlights and reflections will not be accurate if the camera is dynamic. This is a limitation of texture baking in general.
• Any animated shaders will only be baked at the current frame. Unless you bake the texture at every frame, the animation will not be captured. See the performance section for more details.

Performance

Baking shaders is an expensive operation. It is recommended to bake the shaders only once and then use the resulting texture in your scene or export it out. The cost of baking is directly proportional to the size of the baked texture. The larger the texture, the more time it will take to bake.

If you have animated shaders, you will need to bake the texture at every frame to capture the animation. This can be done by calling the bake function at every frame. This is not recommended for real-time applications as it can be very expensive.

At the moment, baking is a synchronous operation. This means that the browser will freeze while the baking is happening. You will also see a flicker in the scene as the process is happening. I will be looking into making this asynchronous in the future.

For now, it is recommended to black out the screen or show a loading screen while the baking is happening.

API Reference

Vanilla

ShaderBaker

ShaderBaker.constructor()

Creates a new instance of the ShaderBaker.

ShaderBaker.bake(renderer: THREE.WebGLRenderer, mesh: THREE.Mesh, options: Object): THREE.WebGLRenderTarget

Bakes the shader/material of the mesh into a render target.

• renderer - The renderer instance.
• mesh - The mesh whose shader/material you want to bake.
• options - Optional options.
  • scene - The scene that the mesh is in. If provided, the current env map will be used.
  • size - Number. Size of the baked texture. Default is 1024.
  • target - THREE.WebGLRenderTarget. If provided, the baked texture will be rendered to this target.
  • dilation - Number. Number of pixels to dilate the texture by. Default is 2. This is useful to prevent seam artifacts.

ShaderBaker.dispose()

Disposes of the ShaderBaker instance and its associated resources.

getTextureAsDataUrl(renderer: THREE.WebGLRenderer, texture: THREE.Texture): string

Converts a texture to a data URL.

downloadTexture(renderer: THREE.WebGLRenderer, texture: THREE.Texture, filename: string): void

Downloads a texture as a png file.

React

<ShaderBaker />

A provider component that provides the useShaderBaker hook. Any THREE.Mesh inside this component will be baked into separate render targets.

This props of this component are as follows:

• size - Number. Size of the baked texture. Default is 1024.
• dilation - Number. Number of pixels to dilate the texture by. Default is 2. This is useful to prevent seam artifacts.

<ShaderBakerExclusion />

A component that excludes a THREE.Mesh from being baked. Any THREE.Mesh inside this component will be excluded from baking.

You can manually exclude meshes by setting THREE.Mesh.userData["__shaderBaker_isExcluded"] = true.

const obj = useShaderBaker()

A hook that returns useful functions and data for baking. The object returned has the following properties:

• bake(args): { [mesh.uuid]: THREE.WebGLRenderTarget }
  • This function bakes all the meshes inside the <ShaderBaker /> component.
  • The args are as follows:
    • mesh: mesh: THREE.Mesh | THREE.Mesh[] | null - The mesh(es) to bake. If not provided, all meshes inside the <ShaderBaker /> component will be baked.
    • options: Object
      • dialetion - Number. Number of pixels to dilate the texture by. Default is 2. This is useful to prevent seam artifacts.
      • size - Number. Size of the baked texture. Default is 1024.
• renderTargets: { [key: string]: THREE.WebGLRenderTarget }
  • An object containing all the render targets of the baked meshes. Keyed by the their respective mesh's uuid.
• textures: { [key: string]: THREE.Texture }
  • An object containing all the textures of the baked meshes (THREE.WebGLRenderTarget.texture). Keyed by the their respective mesh's uuid.

getTextureAsDataUrl(renderer: THREE.WebGLRenderer, texture: THREE.Texture): string

Converts a texture to a data URL.

downloadTexture(renderer: THREE.WebGLRenderer, texture: THREE.Texture, filename: string): void

Downloads a texture as a png file.