Skip to content

Releases

v0.1.0

Choose a tag to compare

@Zyie Zyie released this 12 Nov 14:48

PixiJS 3D is public. Combine 2D and 3D in one place, the PixiJS way.

npm install pixi.js @pixi/3d

🚨 Behavior Change since 0.1.0-beta.3

  • @pixi/3d ships ES modules only. The CommonJS build never loaded; on Node 20.19+ and 22.12+, require('@pixi/3d') now loads the ES modules. (#34)
  • The CDN files are pixijs-3d.min.mjs and pixijs-3d-extras.min.mjs, renamed from pixi-3d….
  • Warnings start with [@pixi/3d], and the math types' toString() returns [@pixi/3d/math:Vector3 …].

🐛 Fixed

  • Importing @pixi/3d/extras before @pixi/3d no longer throws "Class extends value undefined". (#34)

v0.1.0-beta.3

Choose a tag to compare

@github-actions github-actions released this 11 Nov 23:00

Closed beta build of @pixi/3d, from commit 97ece7a.

Download pixi-3d-0.1.0-beta.3.tgz, then install it next to PixiJS:

npm install pixi.js@^8.23.0
npm install ./pixi-3d-0.1.0-beta.3.tgz

Imports work exactly as they will from npm:

import { View3D } from '@pixi/3d';
import { OrbitCamera } from '@pixi/3d/extras';

🚨 Behavior Change

  • chore: bump pixi.js peer dependency to 8.23.0 by @Zyie
    npm install pixi.js@^8.23.0
  • feat: views default to toneMapping 'none' by @GoodBoyDigital
    • View3D now defaults to toneMapping: 'none' instead of 'aces'. A scene that relied on the default draws its highlights brighter, and lit colour above 1 clips to white instead of rolling off. Unlit materials and a background colour now show as authored, where ACES drew white as light grey. To keep beta.2's look, pass toneMapping: 'aces' to each view, or set View3D.defaultOptions.toneMapping = 'aces' once before you create any view.
    import { View3D } from '@pixi/3d';
    
    // one view
    const view3d = new View3D({ toneMapping: 'aces' });
    
    // or every view created after this line
    View3D.defaultOptions.toneMapping = 'aces';
  • feat: post effects read linear light, with the curve in OutputPass by @GoodBoyDigital
    • PassStage no longer has 'post'. Post effects run at 'beforeToneMapping', on linear light before the view's tone curve, or at the new 'afterToneMapping', on the picture as it shows, and PostEffect.stage is one of the two. Replace checks for 'post', and replace Exclude<PassStage, 'post'> with the new SceneStage type, which MeshPassOptions.stage and WireframePassOptions.stage now take.
    import type { PassStage, SceneStage } from '@pixi/3d';
    
    // before
    const stage: Exclude<PassStage, 'post'> = 'afterOpaque';
    const isEffect = pass.stage === 'post';
    
    // after
    const stage: SceneStage = 'afterOpaque';
    const isEffect = pass.stage === 'beforeToneMapping' || pass.stage === 'afterToneMapping';
    • A custom PostEffect runs at 'beforeToneMapping' unless it says otherwise. Its input is linear light in rgba16float, so values can go above 1 and aren't display-encoded. An effect that works on the picture as it shows, such as LUT grading or edge detection, or that shows data such as depth, normals or debug colours, must pass stage: 'afterToneMapping' to super.
    import { PostEffect } from '@pixi/3d';
    import type { PostEffectOptions } from '@pixi/3d';
    
    class MyLutEffect extends PostEffect {
      constructor(options: PostEffectOptions = {}) {
        super({ stage: 'afterToneMapping', ...options });
      }
    }
    • Effects now run grouped by stage: every 'beforeToneMapping' effect in array order, then the tone curve, then every 'afterToneMapping' effect in array order. TintEffect defaults to 'afterToneMapping', so it runs after BloomEffect, SsaoEffect and TiltShiftEffect wherever it sits in view.passes. To keep a tint ahead of them, give it stage: 'beforeToneMapping'; it then tints the light instead of the picture.
    import { BloomEffect, TintEffect } from '@pixi/3d/extras';
    
    // before: the tint ran first because it came first in the array
    view3d.passes = [new TintEffect({ tint: 0xffaa66 }), new BloomEffect()];
    
    // after
    view3d.passes = [new TintEffect({ tint: 0xffaa66, stage: 'beforeToneMapping' }), new BloomEffect()];
    • A view with a 'beforeToneMapping' effect, such as BloomEffect, SsaoEffect, TiltShiftEffect or a custom PostEffect, now draws its scene into rgba16float linear light. Its toneMapping curve then runs once on the whole image after those effects, not in each material. Transparent surfaces blend in linear light before the curve, so they look slightly different. Views without such an effect keep the curve in their materials.
    • BloomEffect now reads linear light before the tone curve, so every bloom looks different. Its threshold is measured in that light, and the default 1 blooms only what's brighter than white. Retune a threshold set for the old 8-bit image, such as 0.5.
    • SsaoEffect now darkens linear light before the tone curve, so its occlusion looks lighter. Raise intensity to match the old look. TiltShiftEffect also blurs in linear light now.
    • Glass (a Material3D with transmission) now decodes the scene behind it with an exact 2.2 gamma instead of squaring it, so it looks slightly different in every view. No code change is needed.
    • In a view with a 'beforeToneMapping' effect, OutlinePass, WireframePass and any other MeshPass whose own shader writes a flat colour into the scene no longer show the colour you set. The output pass runs the tone curve and display encode over it, so most colours show lighter; black stays black. Under the default toneMapping: 'none', give the pass its colour in linear light, each channel raised to the power 2.2, to get the old colour back. Under a filmic curve, keep coloured outlines and wireframes in views whose effects all run at 'afterToneMapping'.
    import { Color } from 'pixi.js';
    import { BloomEffect, OutlinePass } from '@pixi/3d/extras';
    
    const [r, g, b] = new Color(0xff8800).toRgbArray();
    view3d.passes = [new OutlinePass({ color: [r ** 2.2, g ** 2.2, b ** 2.2] }), new BloomEffect()];
    • On WebGL 2 without EXT_color_buffer_float, a view with a 'beforeToneMapping' effect now throws when it builds its render graph on its first render. To keep the effect working on those devices, run it at 'afterToneMapping' there.
    import { RendererType } from 'pixi.js';
    import type { WebGLRenderer } from 'pixi.js';
    import { BloomEffect } from '@pixi/3d/extras';
    
    const renderer = app.renderer;
    const canDrawFloat =
      renderer.type !== RendererType.WEBGL || !!(renderer as WebGLRenderer).context.extensions.colorBufferFloat;
    view3d.passes = [new BloomEffect({ stage: canDrawFloat ? 'beforeToneMapping' : 'afterToneMapping' })];
    • graph.createColor() with no format now takes the scene colour's format, which is rgba16float in a view with a 'beforeToneMapping' effect, where it used to take the view target's. Pass format to keep a texture 8-bit.
    // before
    const mask = graph.createColor({ label: 'mask' });
    
    // after
    const mask = graph.createColor({ label: 'mask', format: 'rgba8unorm' });
    • DefaultGraph3DOptions.toneMapping is now required. A custom graph builder that passes the options it receives on to createDefaultGraph3D gets it from the view. A builder that writes its own options object must spread options into it; in plain JavaScript, leaving it out shows a view with a 'beforeToneMapping' effect without its tone curve or display encode.
    import { createDefaultGraph3D } from '@pixi/3d';
    import type { View3DOptions } from '@pixi/3d';
    
    // before
    const graph: View3DOptions['graph'] = (renderer, options) =>
      createDefaultGraph3D(renderer, { passes: options.passes, composite: true }).graph;
    
    // after
    const graph: View3DOptions['graph'] = (renderer, options) =>
      createDefaultGraph3D(renderer, { ...options, composite: true }).graph;
    • Lit material shaders on both backends now define a decodeToLinear(c) function. A custom bit that defines a function with that name fails to compile, so rename yours.
    • In a custom graph builder, a sceneColor with a float or -srgb format, such as rgba16float, now marks the scene as linear light (RenderGraph.sceneIsLinear). Materials and the sky then leave out the tone curve and display encode, so the image shows too dark unless a pass in the graph applies them. In beta.2 the materials always applied them. Finish such a graph with an OutputPass given the builder's options.toneMapping. On such a view, and on any view with a 'beforeToneMapping' effect, changing toneMapping now destroys the render graph and calls the builder again, so don't keep references to the passes it made.
    import { OutputPass, RenderGraph } from '@pixi/3d';
    import type { View3DOptions } from '@pixi/3d';
    
    const buildGraph: View3DOptions['graph'] = (renderer, options) => {
      const graph = new RenderGraph({
        globalTextureBindings: options.globalTextureBindings,
        defaultColor: (session) => session.defaultTarget.colorTexture,
        defaultDepth: (session) => session.defaultTarget.depthStencilTexture!,
        sceneColor: { label: 'sceneColor', format: 'rgba16float' },
        sceneDepth: { label: 'sceneDepth' },
      });
    
      // add your passes, then finish the image
      graph.addPass(new OutputPass({ renderer, source: graph.sceneColor, toneMapping: options.toneMapping }));
    
      return graph;
    };
  • fix: unlit materials show colours as authored by @GoodBoyDigital
    • BaseMaterial3D.toneMapped is removed, and every material, lit or unlit, now takes the view's toneMapping. Delete toneMapped overrides and any reads or writes of it; TypeScript rejects override toneMapped. There's no per-material opt-out. Under toneMapping: 'none', the default, unlit art at exposure 1 matches pixi 2D, and under a filmic curve such as 'aces' it shifts with the lit scene. To keep some art off the curve, draw it in its own View3D with toneMapping: 'none'.
    // before
    class SkyMaterial extends BaseMaterial3D {
      public override toneMapped = false;
      public override lit = false;
    }
    
    // after
    class SkyMaterial extends BaseMaterial3D {
      public override lit = false;
    }
    • FlatMaterial, Sprite3D, ParticleContainer3D and ParticleSystem3D particles, PortalMaterial and glTF KHR_materials_unlit materials now encode their colour inputs for display, so they render differently with no code change. Beta.2 drew their baseColor, tint, particle color and colorEnd, vertex colours and glTF unlit factors as linear values (a 128 grey drew as 55). Under toneMapping: 'none' at exposure 1 ...
Read more

v0.1.0-beta.2

Choose a tag to compare

@github-actions github-actions released this 01 Oct 22:22

Closed beta build of @pixi/3d, from commit bdb9eb4.

Download pixi-3d-0.1.0-beta.2.tgz, then install it next to PixiJS:

npm install pixi.js
npm install ./pixi-3d-0.1.0-beta.2.tgz

Imports work exactly as they will from npm:

import { View3D } from '@pixi/3d';
import { OrbitCamera } from '@pixi/3d/extras';

🚨 Behavior Change

  • chore: bump pixi.js peer dependency to 8.22.0 by @Zyie
    npm install pixi.js@^8.22.0
  • breaking: read material rows from the data texture on WebGPU by @GoodBoyDigital
    • This affects custom shader bits that declare material fields.
    • A material field must be f32, u32, i32, a vec2, vec3 or vec4 of f32, or mat2x2<f32>. Creating a material with any other type throws, and the error names the bit and the field. A material struct larger than its 256-byte row also throws, where it used to spill into the next material's data.
    • In WGSL, uMaterialStorage is a texture now, so uMaterialStorage[i] no longer compiles. Read the material local, which both stages have, or call getMaterial(index) for another material's row.
    // before
    let tint = uMaterialStorage[vMaterialIndex].tint;
    // after
    let tint = material.tint;
    • In GLSL, the compiler emits getMaterial() after gl.header, so code in the header can't call it. Code in the stage slots still can.
  • fix: WebGPU batch samplers take the implicit level of detail by @GoodBoyDigital
    • The shader helpers sampleBatchTexture and _unpackSlot are gone from the WGSL and GLSL headers, so a custom ShaderBit that calls them fails to compile. Call the generated sample<Name>(uv) and sample<Name>Direct(uv) getters instead, or sampleBatchSlotGrad(slot, uv, dx, dy) with the slot read from _textureSlots in WGSL or vTextureSlots in GLSL.
  • feat: BatchedMesh3D cull option by @GoodBoyDigital
    • A BatchedMesh3D no longer takes its culling mode from the view. Each batch has its own cull, and it defaults to 'off', so every instance draws. In beta.1 a batch followed the view's cull, which defaults to 'auto'. Turn culling back on for a large batch spread well beyond the view, such as scattered scenery:
    const forest = new BatchedMesh3D({ size: treePositions.length, cull: 'auto' });
  • feat: OrbitCamera and FPSCamera keep the context menu from opening by @Zyie
    • Once a View has an OrbitCamera or FPSCamera, the browser's context menu stops opening over that View. Pass preventContextMenu: false to get it back. The menu also opens while the controller's enabled is false.
    import { OrbitCamera } from '@pixi/3d/extras';
    
    new OrbitCamera({ view: view3d, preventContextMenu: false });
    
    // or for every controller created after this line
    OrbitCamera.defaultOptions.preventContextMenu = false;

🎁 Added

  • feat: View3D.background accepts a Hemisphere by @Zyie
    • View3D's background takes a Hemisphere and draws its sky and ground gradient behind the scene, on WebGL and WebGPU. The gradient uses the same formula as a hemisphere environment, so one object passed to both gives a sky that matches the scene's light. The view's exposure and tone mapping apply, as they do to a cube map. A colour change shows on the next frame. The option also accepts null.
    import { type Hemisphere, View3D } from '@pixi/3d';
    
    const sky: Hemisphere = { skyColor: 0x88ccff, groundColor: 0x553311 };
    const view3d = new View3D({ autoResize: true, environment: sky, background: sky });
    
    sky.skyColor = 0xff8800; // sunset
  • feat: OrbitCamera and FPSCamera keep the context menu from opening by @Zyie
    • OrbitCamera and FPSCamera take a preventContextMenu option, also a property you can change at runtime. It defaults to true, so a right-button pan or a drag to look around no longer opens the browser menu. Windows opens the menu on release, so there a right-button drag that ends outside the View still opens it.
    • 3D nodes receive contextmenu events like the other pointer events, with hit3D set, and gain an oncontextmenu handler property. preventDefault() keeps the browser menu closed. stopPropagation() lets it open and hides the event from the View's own listeners, such as a camera controller's.
    mesh.on('contextmenu', (e) => {
      e.preventDefault();
      openMenuFor(mesh, e.global);
    });
  • feat: read material rows from the data texture on WebGPU by @GoodBoyDigital

⚡ Performance

🐛 Fixed

  • fix: WebGL reads integer data through integer textures by @GoodBoyDigital
  • fix: use the glTF default material for primitives without one by @Zyie
  • fix: WebGL reads integer data through integer textures by @GoodBoyDigital
  • chore: bump pixi.js peer dependency to 8.22.0 by @Zyie
  • fix: shadow auto-fit reads live caster membership, not a stale sort by @Zyie
  • fix: apply View3D visibility and transform changes by @Zyie
  • fix: keep the WebGL bone texture aligned to whole rows when the bone pit grows by @Zyie
  • fix: drop the GGX guard that flattened smooth highlights by @Zyie
  • fix: copy atlas fast-path vertices as bytes and check the layout first by @GoodBoyDigital
  • fix: copies read the target their camera drew, not whatever is bound by @GoodBoyDigital
  • breaking: read material rows from the data texture on WebGPU by @GoodBoyDigital
  • fix: a read-only-depth pass resolves to pixi's default target instead of reconfiguring the canvas by @Zyie
  • fix: shadow passes let go of pipe stores when their renderer is destroyed by @Zyie
  • fix: IBL prefilter and BRDF LUT release their one-shot bind groups by @Zyie

🧹 Chores

  • chore: fact-check the API docs across src by @Zyie
  • chore: fix the glTF viewer, comparison and walrus-cave examples by @Zyie

v0.1.0-beta.1

Choose a tag to compare

@github-actions github-actions released this 21 Sep 19:51

Closed beta build of @pixi/3d, from commit 1022460.

Download pixi-3d-0.1.0-beta.1.tgz, then install it next to PixiJS:

npm install pixi.js
npm install ./pixi-3d-0.1.0-beta.1.tgz

Imports work exactly as they will from npm:

import { View3D } from '@pixi/3d';
import { OrbitCamera } from '@pixi/3d/extras';

🚨 Behavior Change

  • feat: light tile mask on WebGPU, and one upload per camera by @GoodBoyDigital
    • prepareCamera no longer uploads a camera. uploadCamera does that after the view's lights are packed, and RenderGraph.prepareCameras runs both for every camera the graph draws. If you drive the graph yourself, call prepareCameras; a camera that never reaches uploadCamera keeps all-set tile masks and walks every light slot, which is correct but slower.
  • feat: WebGPU reads lights and shadow data from the global uniforms, like WebGL by @GoodBoyDigital
    • The WGSL storage buffers uLightStorage and uShadowStorage are gone. Both backends now read the same two uniform arrays, uLightData and uShadowData, from the global group. A custom WGSL shader bit that read either storage buffer must switch to the global arrays. WGSL bindings are numbered in declaration order, so the global-group bindings after the removed pair shifted down by two.
  • feat: screen-tile light mask for the WebGL forward light loop by @GoodBoyDigital
    • A custom material built with createLightingBit now needs the camera bindings, because the light loop reads the tile mask and the viewport from the camera group. includeCamera is on by default; leave it on. The same applies on WebGPU.

🎁 Added

  • feat: View3D.from and autoResize by @Zyie
    • View3D.from(source, options) turns a loaded glTF into a working scene in one call. The Model3D becomes the View's root, the file's own camera is used when it has one, otherwise a default Camera3D is placed to frame the model's bounds, and a file with no lights gets a key light parented under the camera. Pass light: false to skip that light. View3D is generic over its root, so from returns View3D<Model3D> and view.root is typed as the model. Options are every View3DOptions field plus the per-instance Model3D ones (scene, castShadow, receiveShadow, autoPlay, autoUpdate). glTF camera nodes now instantiate as Camera3D and are listed on model.cameras; they were plain containers before.
    import { Assets } from 'pixi.js';
    import { View3D } from '@pixi/3d';
    
    const view = View3D.from(await Assets.load('robot.glb'), { autoResize: true });
    
    app.stage.addChild(view);
    view.root.player?.play('Wave');
    • The new autoResize option, off by default, makes a View fill the renderer's screen and follow it. The size is applied in pixi's per-frame onRender hook, before the frame's bounds and instructions are built, so filters and hit-testing see the new rect in the same frame. Setting a size later turns autoResize off, so an explicit size always wins. This is what the examples used to hand-roll:
    // before
    const view3d = new View3D({
      width: app.screen.width,
      height: app.screen.height,
      shadowQuality: 'high',
    });
    
    app.ticker.add(() => {
      view3d.setSize(app.screen.width, app.screen.height);
    });
    
    // after
    const view3d = new View3D({ autoResize: true, shadowQuality: 'high' });
  • feat: write BatchedMesh3D matrices in place by @GoodBoyDigital
    • BatchedMesh3D.matrices exposes the batch's interleaved instance data, so a per-frame transform update can be computed straight into it instead of building a Matrix4 and copying it through setMatrixAt. Call matrices.update() once after writing to notify the batch. About 2.3 ms saved per frame at 500,000 instances on an M-series Mac.
    const { data, stride, offset } = batched.matrices;
    
    for (let i = 0, o = offset; i < batched.size; i++, o += stride) {
      data[o + 13] = heights[i]; // translation Y
    }
    
    batched.matrices.update();

⚡ Performance

  • feat: screen-tile light mask for the WebGL forward light loop by @GoodBoyDigital
  • feat: light tile mask on WebGPU, and one upload per camera by @GoodBoyDigital
  • feat: cull lights by camera depth and skip empty WebGL mask bits by @GoodBoyDigital
  • perf: no environment lighting work for a view with no environment by @GoodBoyDigital
  • perf: draw alpha-masked meshes after the opaque ones in a pass by @GoodBoyDigital
  • perf: WebGPU reads lights and shadow data from the global uniforms, like WebGL by @GoodBoyDigital
  • perf: lit shaders leave shadow sampling out until a light first casts by @GoodBoyDigital

🐛 Fixed

  • fix: loader parsers carry the name pixi's validator hashes on by @Zyie
  • fix: the WebGL group map stops warning about struct-only bind groups by @Zyie
  • fix: glTF custom-attribute notices go through pixi's warn, once per semantic by @Zyie
  • fix: the back-buffer notice for glass warns once per renderer by @Zyie
  • fix: WebGL shader precision comes from one compiler plugin, plus IBL hardening by @GoodBoyDigital
  • fix: WebGPU shadow lookup takes two floats, not the light struct by @GoodBoyDigital
  • fix: fast-path default WebGPU texture values by @GoodBoyDigital
  • fix: WebGPU batch texture sampling stalls on Apple GPUs with MSAA by @GoodBoyDigital
  • fix: shadow pass no longer runs for lights that cannot cast by @GoodBoyDigital

🧹 Chores

  • chore: drop the View3D resize boilerplate from the examples by @Zyie