@masatomakino/threejs-billboard
threejs-billboard
billboard module for three.js
Demo
Getting Started
Install
npm install @masatomakino/threejs-billboard --save-dev
threejs-billboard depend on three.js and pixi.js.
Import
threejs-billboard is composed of ES6 modules and TypeScript d.ts files.
At first, import classes.
import {
BillBoard,
StageBillBoard,
StagePlaneMesh,
ScaleCalculator,
} from "@masatomakino/threejs-billboard";
Show billboard
Add billboard in THREE.Scene.
const billboard = new BillBoard("./map01.png", 0.1);
scene.add(billboard);
Choosing the Right Class
The library provides different classes for creating billboards and plane meshes, each with distinct characteristics and use cases:
- Image-based Classes (BillBoard, BillBoardPlane): Use image files as source. Simple to use for static images.
- SharedStage Classes (Billboard, PlaneMesh): Utilize a single shared Canvas/Texture, excelling in reducing draw calls. Suitable for scenarios with a fixed number of billboards where performance is critical.
- MultiView Classes (Billboard, PlaneMesh): Each instance has an independent Canvas, offering superior performance for partial updates and flexibility in the number of billboards. Suitable for scenarios with numerous and dynamically changing billboards.
Dot-by-dot display
If you want to display dot-by-dot billboard, get image scale with ScaleCalculator.
const scale = ScaleCalculator.getNonAttenuateScale(
renderer.getSize(new THREE.Vector2()).height,
camera,
);
const billboard = new BillBoard("./map01.png", scale);
billboard.material.sizeAttenuation = false;
Camera Chaser
The CameraChaser utility can be used with SharedStagePlaneMesh, MultiViewPixiPlaneMesh, and BillBoardPlane to make the plane track the camera's rotation. By default, this feature is off. You can enable it to make the plane always face the camera, similar to a billboard but maintaining its plane geometry. Note that unlike a Sprite, the rotation is limited to the Y-axis.