跳到主要内容

宽线

WebGL 和 WebGPU 原生只能绘制一像素宽的线。WideLineRenderer 将每段绘制为面向相机的几何体，实现真正有宽度、圆头、斜接角、虚线和颜色渐变的线。

适用于作为场景内容的线几何体，例如高亮路线、道路网络、测量标注或轨迹。开发时检查场景所需的单像素线框，请参见调试绘制。

线与渲染器​

系统包含两部分：WideLine 保存一条线的点数据，WideLineRenderer 拥有并绘制一组线：

import { LINECAP_ROUND, LINEJOIN_ROUND, WideLine, WideLineRenderer } from 'playcanvas';

const renderer = new WideLineRenderer(app);
const line = new WideLine();

line.set(
    new Float32Array([-2, 0, 0, 0, 1, 0, 2, 0, 0]),   // three points, packed xyz
    new Float32Array([1, 0, 0, 1, 1, 0, 0, 1, 1]),    // a colour per point, packed rgb
    new Float32Array([4, 12, 4])                       // a width per point
);
line.cap = LINECAP_ROUND;
line.join = LINEJOIN_ROUND;

renderer.add(line);

app.on('destroy', () => renderer.destroy());

与调试绘制不同，这是保留式的：添加一次后，线会一直存在，直到调用 remove()，无需每帧重新提交。

颜色和宽度均可逐点提供，也可用单个值应用到所有点。

设置线的样式​

以下是 WideLine 的属性，因此同一渲染器内各条线可以具有不同外观：

属性用途
cap端点形状：LINECAP_BUTT、LINECAP_ROUND 或 LINECAP_SQUARE。
join转角连接方式：LINEJOIN_MITER、LINEJOIN_BEVEL 或 LINEJOIN_ROUND。
closed将最后一点连接回第一点。
dashLength, gapLength虚线模式，dashLength 为零时是实线。
dashOffset沿线移动虚线图案，用于蚂蚁线动画。

更新点数据​

setPositions、setColors 和 setWidths 分别替换对应数据，保持点数量不变，并复用现有存储：

line.setPositions(updatedPositions);

需要改变点数量时，使用 set()。

渲染器设置​

属性用途
widthUnits默认 LINEWIDTH_SCREEN 以屏幕像素计量，任意距离下保持线宽。LINEWIDTH_WORLD 以世界单位计量，像几何体一样随距离缩小。
layer渲染到的图层，默认为 Immediate 图层。
depthTest, depthWrite与深度缓冲区的交互，默认均为 true。
enabled关闭整个渲染器。
capacity实例缓冲区容量，以线段数计量。

性能​

每条线段作为一个 GPU 实例绘制，渲染器的全部线段一起提交，因此增加 WideLine 不会增加绘制调用。每台渲染其图层的相机，对具有可见线段的渲染器只需一次绘制调用。

代价是修改任意一条线，都会重建该渲染器拥有的全部线的实例数据。因此，把很少变化和频繁变化的线混在一起，会导致静态数据无谓重建。没有静态/动态标志，应使用两个渲染器分开：

const staticLines = new WideLineRenderer(app);
const dynamicLines = new WideLineRenderer(app);

staticLines.add(roadNetwork);       // built and uploaded once
dynamicLines.add(projectilePath);   // updated every frame

capacity 会自动增长，但已知最大线段数时，预先设置可避免 GPU 缓冲区重新分配。clear() 移除所有线，但保留容量供复用。

整批不进行视锥体剔除，因此不需要绘制任何线时，将 enabled 设为 false。

限制​

  • **仅不透明渲染。**颜色使用 rgb，忽略 Color 的 alpha 分量，不支持透明线。
  • 调用 destroy() 释放网格、材质和实例缓冲区。以此方式脱离的线仍可使用，也可加入其他渲染器。

示例​