Fix/rendering/per pass ubo upload (#432)

* fix(rendering): track UBO upload state per buffer and isolate layout UBO state

* fix(rendering): deduplicate bound UBO buffers and release on pipeline destroy

* refactor(rendering): simplify per-pass UBO helpers and reduce bundle size

---------

Co-authored-by: vanitynie <vanitynie@qq.com>
This commit is contained in:
Ming
2026-11-18 18:12:23 +08:00
committed by GitHub
parent 5313b86ed1
commit 229ad74757
4 changed files with 612 additions and 168 deletions
+130 -141
View File
@@ -26,7 +26,6 @@
import { BufferInfo, Buffer, BufferUsageBit, ClearFlagBit, Color, DescriptorSet, LoadOp,
Format, Rect, Sampler, StoreOp, Texture, Viewport, MemoryUsageBit,
UniformBlock,
Device,
} from '../../gfx';
import { ReflectionProbe } from '../../render-scene/scene/reflection-probe';
import { Camera, SkyBoxFlagValue } from '../../render-scene/scene/camera';
@@ -446,58 +445,109 @@ export function getDescBindingFromName (bindingName: string): number {
return -1;
}
const uploadedUniforms = new WeakMap<Buffer, Float32Array>();
function isUniformChanged (cached: Float32Array, values: number[]): boolean {
return cached.length !== values.length || values.some((v, i) => !Object.is(Math.fround(v), cached[i]));
}
class DescBuffManager {
private buffers: Buffer[] = [];
private currBuffIdx: number = 0;
private device: Device;
public currUniform: Float32Array;
private _root;
private currUniform: Float32Array;
private lastUploadedBuffer: Buffer | null = null;
constructor (bufferSize: number, numBuffers: number = 2) {
const root = this._root = cclegacy.director.root;
const device = root.device;
this.device = device;
const root = cclegacy.director.root;
const device = (root.pipeline as WebPipeline)?.device || root.device;
const { buffers } = this;
const bufferInfo = new BufferInfo(
BufferUsageBit.UNIFORM | BufferUsageBit.TRANSFER_DST,
MemoryUsageBit.HOST | MemoryUsageBit.DEVICE,
bufferSize,
bufferSize,
);
this.currUniform = new Float32Array(bufferSize / 4);
for (let i = 0; i < numBuffers; i++) {
const bufferInfo: BufferInfo = new BufferInfo(
BufferUsageBit.UNIFORM | BufferUsageBit.TRANSFER_DST,
MemoryUsageBit.HOST | MemoryUsageBit.DEVICE,
bufferSize,
bufferSize,
);
this.buffers.push(this.device.createBuffer(bufferInfo));
buffers.push(device.createBuffer(bufferInfo));
}
}
getCurrentBuffer (): Buffer {
const { director } = cclegacy;
this.currBuffIdx = director.getTotalFrames() % this.buffers.length;
return this.buffers[this.currBuffIdx];
updateBuffer (binding: number, descriptorSet: DescriptorSet, values: number[]): void {
const { buffers, currUniform } = this;
let lastBuf = this.lastUploadedBuffer;
if (!lastBuf || isUniformChanged(currUniform, values)) {
if (lastBuf) {
uploadedUniforms.delete(lastBuf);
}
lastBuf = buffers[this.currBuffIdx];
this.currBuffIdx = (this.currBuffIdx + 1) % buffers.length;
currUniform.set(values);
lastBuf.update(currUniform);
uploadedUniforms.set(lastBuf, currUniform);
this.lastUploadedBuffer = lastBuf;
}
descriptorSet.bindBuffer(binding, lastBuf);
}
updateData (vals: number[]): void {
this.currUniform.set(vals);
}
updateBuffer (bindId: number, setData: DescriptorSetData): void {
const descriptorSet = setData.descriptorSet!;
const buffer = this.getCurrentBuffer();
buffer.update(this.currUniform);
bindGlobalDesc(descriptorSet, bindId, buffer);
destroy (): void {
const { buffers } = this;
for (const buffer of buffers) {
uploadedUniforms.delete(buffer);
buffer.destroy();
}
buffers.length = 0;
this.lastUploadedBuffer = null;
}
}
const buffsMap: Map<string, DescBuffManager> = new Map();
const currBindBuffs: Map<string, number> = new Map();
interface ConstantBlockInfo {
offset: number;
buffer: number[];
blockId: number;
}
const layouts: Map<string, DescriptorSetData> = new Map();
export function getDescriptorSetDataFromLayout (layoutName: string): DescriptorSetData | undefined {
interface LayoutUBOCache {
descriptorSetData: DescriptorSetData;
uniformBlockMap: Map<number, number[]>;
constantBlockMap: Map<number, ConstantBlockInfo>;
}
const pipelineCaches = new WeakMap<WebPipeline, { buffsMap: Map<string, DescBuffManager>; layouts: Map<string, LayoutUBOCache> }>();
const pendingBlocks: Map<number, number[]> = new Map();
function getUBOCache (webPip: WebPipeline): { buffsMap: Map<string, DescBuffManager>; layouts: Map<string, LayoutUBOCache> } {
let cache = pipelineCaches.get(webPip);
if (!cache) {
cache = { buffsMap: new Map(), layouts: new Map() };
pipelineCaches.set(webPip, cache);
}
return cache;
}
export function destroyUBOCache (webPip: WebPipeline): void {
const cache = pipelineCaches.get(webPip);
if (!cache) { return; }
for (const manager of cache.buffsMap.values()) {
manager.destroy();
}
pipelineCaches.delete(webPip);
}
function getLayoutUBOCache (layoutName: string): LayoutUBOCache | undefined {
const webPip = cclegacy.director.root.pipeline as WebPipeline;
const { layouts } = getUBOCache(webPip);
const descLayout = layouts.get(layoutName);
if (descLayout) {
return descLayout;
}
const webPip = cclegacy.director.root.pipeline as WebPipeline;
const stageId = webPip.layoutGraph.locateChild(webPip.layoutGraph.N, layoutName);
const layout = webPip.layoutGraph.getLayout(stageId);
const layoutData = layout.getSet(UpdateFrequency.PER_PASS);
layouts.set(layoutName, layoutData!);
return layoutData;
const lg = webPip.layoutGraph;
const stageId = lg.locateChild(lg.N, layoutName);
const layoutData = lg.getLayout(stageId).getSet(UpdateFrequency.PER_PASS);
if (!layoutData) { return undefined; }
const cache: LayoutUBOCache = { descriptorSetData: layoutData, uniformBlockMap: new Map(), constantBlockMap: new Map() };
layouts.set(layoutName, cache);
return cache;
}
export function getDescriptorSetDataFromLayout (layoutName: string): DescriptorSetData | undefined {
return getLayoutUBOCache(layoutName)?.descriptorSetData;
}
export function getDescriptorSetDataFromLayoutId (id: number): DescriptorSetData | undefined {
@@ -507,147 +557,74 @@ export function getDescriptorSetDataFromLayoutId (id: number): DescriptorSetData
return layoutData;
}
export function updateGlobalDescBinding (data: RenderData, sceneId: number, idxRD: number, layoutName = 'default'): void {
updatePerPassUBO(layoutName, sceneId, idxRD, data);
}
function getUniformBlock (block: string, layoutName: string): UniformBlock | undefined {
const webPip = cclegacy.director.root.pipeline as WebPipeline;
const lg = webPip.layoutGraph;
const nodeId = lg.locateChild(0xFFFFFFFF, layoutName);
const ppl = lg.getLayout(nodeId);
const layout = ppl.getSet(UpdateFrequency.PER_PASS)!.descriptorSetLayoutData;
const nameID: number = lg.attributeIndex.get(block)!;
return layout.uniformBlocks.get(nameID);
}
function getUniformOffset (uniform: string, block: string, layout: string): number {
const uniformBlock = getUniformBlock(block, layout);
if (!uniformBlock) return -1;
function getUniformOffset (uniform: string, uniformBlock: UniformBlock): number {
let offset = 0;
for (const currUniform of uniformBlock.members) {
const currCount = getUBOTypeCount(currUniform.type);
if (currUniform.name === uniform) {
return offset;
}
offset += currCount * currUniform.count;
offset += getUBOTypeCount(currUniform.type) * currUniform.count;
}
return -1;
}
const uniformBlockMap: Map<string, number[]> = new Map();
class ConstantBlockInfo {
offset: number = -1;
buffer: number[] = [];
blockId: number = -1;
}
const constantBlockMap: Map<number, ConstantBlockInfo> = new Map();
function copyToConstantBuffer (target: number[], val: number[], offset: number): boolean {
let isImparity = false;
if (offset < 0 || offset > target.length) {
return isImparity;
}
const length = Math.min(val.length, target.length - offset);
for (let i = 0; i < length; i++) {
if (target[offset + i] !== val[i]) {
target[offset + i] = val[i];
isImparity = true;
}
}
return isImparity;
}
function addConstantBuffer (block: string, layout: string): number[] | null {
let buffers = uniformBlockMap.get(block);
function addConstantBuffer (blockId: number, currBlock: UniformBlock, uniformBlockMap: Map<number, number[]>): number[] {
let buffers = uniformBlockMap.get(blockId);
if (buffers) {
return buffers;
}
buffers = [];
const webPip = cclegacy.director.root.pipeline as WebPipeline;
const lg = webPip.layoutGraph;
let currCount = 0;
const currBlock = getUniformBlock(block, layout);
if (!currBlock) return null;
for (const uniform of currBlock.members) {
currCount += getUBOTypeCount(uniform.type) * uniform.count;
}
buffers.length = currCount;
buffers.fill(0);
uniformBlockMap.set(block, buffers);
buffers = new Array<number>(currCount).fill(0);
uniformBlockMap.set(blockId, buffers);
return buffers;
}
function updateGlobalDescBuffer (descKey: string, vals: number[]): void {
let currDescBuff = buffsMap.get(descKey);
if (!currDescBuff) {
buffsMap.set(descKey, new DescBuffManager(vals.length * 4, 2));
currDescBuff = buffsMap.get(descKey);
function updateConstantBlock ({ buffer, blockId, offset }: ConstantBlockInfo, data: number[]): void {
const length = Math.min(data.length, buffer.length - offset);
for (let i = 0; i < length; ++i) {
buffer[offset + i] = data[i];
}
currDescBuff!.updateData(vals);
pendingBlocks.set(blockId, buffer);
}
function updateConstantBlock (
constantBuff: ConstantBlockInfo,
data: number[],
descriptorSetData: DescriptorSetData,
sceneId: number,
idxRD: number,
): void {
const blockId = constantBuff.blockId;
const buffer = constantBuff.buffer;
const isImparity = copyToConstantBuffer(buffer, data, constantBuff.offset);
const bindId = getDescBinding(blockId, descriptorSetData);
const desc = descriptorSetData.descriptorSet!;
if (isImparity || !desc.getBuffer(bindId) && bindId !== -1) {
const descKey = `${blockId}${bindId}${idxRD}${sceneId}`;
currBindBuffs.set(descKey, bindId);
updateGlobalDescBuffer(descKey, buffer);
}
}
function updateDefaultConstantBlock (blockId: number, sceneId: number, idxRD: number, vals: number[], setData: DescriptorSetData): void {
const bindId = getDescBinding(blockId, setData);
if (bindId === -1) { return; }
const descKey = `${blockId}${bindId}${idxRD}${sceneId}`;
currBindBuffs.set(descKey, bindId);
updateGlobalDescBuffer(descKey, vals);
}
export function updatePerPassUBO (layout: string, sceneId: number, idxRD: number, user: RenderData): void {
export function updateGlobalDescBinding (user: RenderData, sceneId: number, layout = 'default'): void {
const { constants, samplers, textures, buffers } = user;
const webPip = cclegacy.director.root.pipeline as WebPipeline;
const { buffsMap } = getUBOCache(webPip);
const lg = webPip.layoutGraph;
const descriptorSetData = getDescriptorSetDataFromLayout(layout)!;
currBindBuffs.clear();
const { descriptorSetData, uniformBlockMap, constantBlockMap } = getLayoutUBOCache(layout)!;
const descriptorSet = descriptorSetData.descriptorSet!;
const uniformBlocks = descriptorSetData.descriptorSetLayoutData.uniformBlocks;
pendingBlocks.clear();
for (const [key, data] of constants) {
let constantBlock = constantBlockMap.get(key);
if (!constantBlock) {
const currMemKey = Array.from(lg.constantIndex).find(([_, v]) => v === key)![0];
for (const [block, blockId] of lg.attributeIndex) {
const constantBuff = addConstantBuffer(block, layout);
if (!constantBuff) continue;
const offset = getUniformOffset(currMemKey, block, layout);
for (const [blockId, uniformBlock] of uniformBlocks) {
const constantBuff = addConstantBuffer(blockId, uniformBlock, uniformBlockMap);
const offset = getUniformOffset(currMemKey, uniformBlock);
// not found
if (offset === -1) {
// Although the current uniformMem does not belong to the current uniform block,
// it does not mean that it should not be bound to the corresponding descriptor.
updateDefaultConstantBlock(blockId, sceneId, idxRD, constantBuff, descriptorSetData);
const binding = getDescBinding(blockId, descriptorSetData);
if (binding !== -1 && !descriptorSet.getBuffer(binding)) {
pendingBlocks.set(blockId, constantBuff);
}
continue;
}
constantBlockMap.set(key, new ConstantBlockInfo());
constantBlock = constantBlockMap.get(key)!;
constantBlock.buffer = constantBuff;
constantBlock.blockId = blockId;
constantBlock.offset = offset;
updateConstantBlock(constantBlock, data, descriptorSetData, sceneId, idxRD);
constantBlock = { buffer: constantBuff, blockId, offset };
constantBlockMap.set(key, constantBlock);
updateConstantBlock(constantBlock, data);
}
} else {
updateConstantBlock(constantBlock, data, descriptorSetData, sceneId, idxRD);
updateConstantBlock(constantBlock, data);
}
}
const descriptorSet = descriptorSetData.descriptorSet!;
for (const [key, value] of textures) {
const bindId = getDescBinding(key, descriptorSetData);
if (bindId === -1) { continue; }
@@ -666,15 +643,27 @@ export function updatePerPassUBO (layout: string, sceneId: number, idxRD: number
bindGlobalDesc(descriptorSet, bindId, value);
}
}
for (const [key, value] of currBindBuffs) {
const buffManager = buffsMap.get(key)!;
buffManager.updateBuffer(value, descriptorSetData);
for (const [blockId, values] of pendingBlocks) {
const binding = getDescBinding(blockId, descriptorSetData);
if (binding === -1) { continue; }
const boundBuffer = descriptorSet.getBuffer(binding);
const boundValues = boundBuffer ? uploadedUniforms.get(boundBuffer) : undefined;
if (boundValues && !isUniformChanged(boundValues, values)) {
continue;
}
const key = `${layout}:${blockId}:${sceneId}`;
let manager = buffsMap.get(key);
if (!manager) {
manager = new DescBuffManager(values.length * 4);
buffsMap.set(key, manager);
}
manager.updateBuffer(binding, descriptorSet, values);
}
for (const [key, value] of buffers) {
const bindId = getDescBinding(key, descriptorSetData);
if (bindId === -1) { continue; }
const buffer = descriptorSet.getBuffer(bindId);
if (!buffer) {
if (buffer !== value) {
bindGlobalDesc(descriptorSet, bindId, value);
}
}
+14 -26
View File
@@ -103,7 +103,6 @@ import {
RasterPass,
RasterSubpass,
RaytracePass,
RenderData,
RenderGraph,
RenderGraphValue,
RenderGraphVisitor,
@@ -773,7 +772,6 @@ class DeviceRenderPass implements RecordingInterface {
protected _layoutName: string;
protected _viewport: Viewport | null = null;
private _layout: RenderPassLayoutInfo | null = null;
private _idxOfRenderData: number = 0;
private _traversalResolves (callback: (resolvePair: ResolvePair) => void): void {
const subpassGraph = this._rasterPass.subpassGraph;
@@ -899,7 +897,6 @@ class DeviceRenderPass implements RecordingInterface {
);
}
get passMergeInfo (): RenderPassMergeInfo { return rpMergeInfos.get(this._rasterPass)!; }
get indexOfRD (): number { return this._idxOfRenderData; }
get rasterID (): number { return this._rasterID; }
get layoutName (): string { return this._layoutName; }
get passID (): number { return this._passID; }
@@ -911,9 +908,6 @@ class DeviceRenderPass implements RecordingInterface {
get clearStencil (): number { return this._clearStencil; }
get deviceQueues (): Map<number, DeviceRenderQueue> { return this._deviceQueues; }
get viewport (): Viewport | null { return this._viewport; }
addIdxOfRD (): void {
this._idxOfRenderData++;
}
visitResource (resName: string): void {
const resourceGraph = context.resourceGraph;
const vertId = resourceGraph.vertex(resName);
@@ -1038,7 +1032,6 @@ class DeviceRenderPass implements RecordingInterface {
this._layoutName = context.renderGraph.getLayout(id);
this._passID = cclegacy.rendering.getPassID(this._layoutName);
this._deviceQueues.clear();
this._idxOfRenderData = 0;
let framebuffer: Framebuffer | null = null;
const colTextures: Texture[] = [];
const currFramebuffer = this._framebuffer;
@@ -1172,8 +1165,9 @@ class DeviceComputePass implements RecordingInterface {
for (const queue of this._deviceQueues) {
queue.record();
}
const renderData = context.renderGraph.getData(this._computeInfo.id);
updateGlobalDescBinding(renderData, -1, 0, context.renderGraph.getLayout(this._computeInfo.id));
const rg = context.renderGraph;
const passId = this._computeInfo.id;
updateGlobalDescBinding(rg.getData(passId), -1, rg.getLayout(passId));
}
resetResource (id: number, pass: ComputePass): void {
@@ -1309,32 +1303,26 @@ class DeviceRenderScene implements RecordingInterface {
recordCommand(context.commandBuffer, this._renderPass, pass, blitDesc.stageDesc!, shader, screenIa);
}
protected _updateGlobal (data: RenderData, sceneId: number): void {
const devicePass = this._currentQueue.devicePass;
devicePass.addIdxOfRD();
updateGlobalDescBinding(data, sceneId, devicePass.indexOfRD, context.renderGraph.getLayout(devicePass.rasterID));
}
protected _updateRenderData (): void {
if (this._currentQueue.isUpdateUBO) return;
const devicePass = this._currentQueue.devicePass;
const queue = this._currentQueue;
if (queue.isUpdateUBO) return;
const devicePass = queue.devicePass;
const rg = context.renderGraph;
const rasterId = devicePass.rasterID;
const passRenderData = context.renderGraph.getData(rasterId);
const layout = rg.getLayout(rasterId);
const sceneId = this.sceneID;
// global
this._updateGlobal(context.renderGraph.globalRenderData, sceneId);
updateGlobalDescBinding(rg.globalRenderData, sceneId, layout);
// pass
this._updateGlobal(passRenderData, sceneId);
updateGlobalDescBinding(rg.getData(rasterId), sceneId, layout);
// queue
const queueId = this._currentQueue.queueId;
const queueRenderData = context.renderGraph.getData(queueId)!;
this._updateGlobal(queueRenderData, sceneId);
updateGlobalDescBinding(rg.getData(queue.queueId)!, sceneId, layout);
// scene
const sceneRenderData = context.renderGraph.getData(sceneId)!;
if (sceneRenderData) this._updateGlobal(sceneRenderData, sceneId);
const sceneRenderData = rg.getData(sceneId);
if (sceneRenderData) updateGlobalDescBinding(sceneRenderData, sceneId, layout);
devicePass.processRenderLayout();
context.passDescriptorSet?.update();
this._currentQueue.isUpdateUBO = true;
queue.isUpdateUBO = true;
}
private _applyViewport (): void {
+2 -1
View File
@@ -45,7 +45,7 @@ import { GeometryRenderer } from '../geometry-renderer';
import { Material } from '../../asset/assets';
import { decideProfilerCamera } from '../pipeline-funcs';
import { DebugViewCompositeType } from '../debug-view';
import { buildReflectionProbePass, genHashValue, resetPassMGState } from './define';
import { buildReflectionProbePass, destroyUBOCache, genHashValue, resetPassMGState } from './define';
import { createGfxDescriptorSetsAndPipelines } from './layout-graph-utils';
import { Root } from '../../root';
import { Scene } from '../../scene-graph';
@@ -1360,6 +1360,7 @@ export class WebPipeline extends WebSetter implements BasicPipeline {
return true;
}
public destroy (): boolean {
destroyUBOCache(this);
this._pipelineSceneData?.destroy();
return true;
}
+466
View File
@@ -0,0 +1,466 @@
import { cclegacy, Vec4 } from '../../cocos/core';
import {
Buffer,
BufferInfo,
BufferUsageBit,
BufferViewInfo,
Color,
DescriptorType,
Format,
LoadOp,
MemoryUsageBit,
Rect,
ShaderStageFlagBit,
StoreOp,
Type,
Uniform,
UniformBlock,
} from '../../cocos/gfx';
import { Executor } from '../../cocos/rendering/custom/executor';
import {
DescriptorBlockData,
DescriptorData,
DescriptorSetData,
DescriptorSetLayoutData,
DescriptorTypeOrder,
LayoutGraphData,
LayoutGraphDataValue,
PipelineLayoutData,
RenderPhaseData,
RenderStageData,
} from '../../cocos/rendering/custom/layout-graph';
import { QueueHint, ResourceResidency, UpdateFrequency } from '../../cocos/rendering/custom/types';
import { WebPipeline } from '../../cocos/rendering/custom/web-pipeline';
interface TrackedUBOStats {
liveBytes: number;
bufferWords: Map<Buffer, Uint32Array>;
restore: () => void;
}
function trackUniformBuffers (): TrackedUBOStats {
const device = cclegacy.director.root.device;
const origCreateBuffer = device.createBuffer.bind(device);
const bufferSizes = new Map<Buffer, number>();
const bufferWords = new Map<Buffer, Uint32Array>();
const stats: TrackedUBOStats = {
liveBytes: 0,
bufferWords,
restore: (): void => {},
};
const spy = jest.spyOn(device, 'createBuffer').mockImplementation((info: BufferInfo | BufferViewInfo): Buffer => {
const buf = origCreateBuffer(info as any);
if (!('buffer' in info) && (info.usage & BufferUsageBit.UNIFORM)) {
const byteSize = info.size;
bufferSizes.set(buf, byteSize);
bufferWords.set(buf, new Uint32Array(byteSize / 4));
stats.liveBytes += byteSize;
const origUpdate = buf.update.bind(buf);
jest.spyOn(buf, 'update').mockImplementation((data: BufferSource, size?: number): void => {
const view = ArrayBuffer.isView(data)
? new Uint8Array(data.buffer, data.byteOffset, size ?? data.byteLength)
: new Uint8Array(data, 0, size ?? data.byteLength);
const dst = new Uint8Array(bufferWords.get(buf)!.buffer);
dst.set(view.subarray(0, dst.byteLength));
origUpdate(data, size);
});
const origDestroy = buf.destroy.bind(buf);
jest.spyOn(buf, 'destroy').mockImplementation((): void => {
const trackedSize = bufferSizes.get(buf);
if (trackedSize !== undefined) {
stats.liveBytes -= trackedSize;
bufferSizes.delete(buf);
bufferWords.delete(buf);
}
origDestroy();
});
}
return buf;
});
stats.restore = (): void => {
spy.mockRestore();
};
return stats;
}
function addStageWithUBOs (
lg: LayoutGraphData,
stageName: string,
blocks: Array<{ blockId: number; binding: number; blockName: string; members: Uniform[] }>,
): number {
const stageLayout = new PipelineLayoutData();
const layoutData = new DescriptorSetLayoutData();
const descBlock = new DescriptorBlockData(
DescriptorTypeOrder.UNIFORM_BUFFER,
ShaderStageFlagBit.ALL,
blocks.length,
);
descBlock.offset = 0;
for (const b of blocks) {
descBlock.descriptors.push(new DescriptorData(b.blockId, Type.UNKNOWN, 1));
layoutData.uniformBlocks.set(b.blockId, new UniformBlock(UpdateFrequency.PER_PASS, b.binding, b.blockName, b.members, 1));
layoutData.bindingMap.set(b.blockId, b.binding);
}
layoutData.descriptorBlocks.push(descBlock);
const setData = new DescriptorSetData(layoutData);
stageLayout.getSets().set(UpdateFrequency.PER_PASS, setData);
const stageId = lg.addVertex<LayoutGraphDataValue.RenderStage>(
LayoutGraphDataValue.RenderStage,
new RenderStageData(),
stageName,
UpdateFrequency.PER_PASS,
stageLayout,
);
lg.addVertex<LayoutGraphDataValue.RenderPhase>(
LayoutGraphDataValue.RenderPhase,
new RenderPhaseData(),
'default',
UpdateFrequency.PER_PHASE,
new PipelineLayoutData(),
stageId,
);
return stageId;
}
function createUBOTestPipeline (twoVec4 = false, includeGlobalInCustomStages = true, suffix = ''): {
ppl: WebPipeline;
stageA: string;
stageB: string;
cleanup: () => void;
getBoundBuffer: (layoutName: string, binding?: number) => Buffer;
} {
const lg = new LayoutGraphData();
const constantNames = ['cc_time', 'cc_screenSize', 'cc_nativeSize', 'cc_debug_view_mode', 'bugParam', 'bugExtra'];
constantNames.forEach((name, idx) => {
lg.constantIndex.set(name, idx);
});
const blockNames = ['CCGlobal', 'BugUBO'];
blockNames.forEach((name, idx) => {
lg.attributeIndex.set(name, idx);
});
const globalMembers = [
new Uniform('cc_time', Type.FLOAT4, 1),
new Uniform('cc_screenSize', Type.FLOAT4, 1),
new Uniform('cc_nativeSize', Type.FLOAT4, 1),
new Uniform('cc_debug_view_mode', Type.FLOAT4, 1),
];
const bugMembers = twoVec4
? [new Uniform('bugParam', Type.FLOAT4, 1), new Uniform('bugExtra', Type.FLOAT4, 1)]
: [new Uniform('bugParam', Type.FLOAT4, 1)];
const bugBinding = includeGlobalInCustomStages ? 1 : 0;
const customBlocks = includeGlobalInCustomStages
? [
{ blockId: 0, binding: 0, blockName: 'CCGlobal', members: globalMembers },
{ blockId: 1, binding: bugBinding, blockName: 'BugUBO', members: bugMembers },
]
: [
{ blockId: 1, binding: bugBinding, blockName: 'BugUBO', members: bugMembers },
];
const stageA = `ubo-bug-a${suffix}`;
const stageB = `ubo-bug-b${suffix}`;
const defaultStage = addStageWithUBOs(lg, 'default', [
{ blockId: 0, binding: 0, blockName: 'CCGlobal', members: globalMembers },
]);
addStageWithUBOs(lg, stageA, customBlocks);
addStageWithUBOs(lg, stageB, customBlocks);
const ppl = new WebPipeline(lg);
jest.spyOn(ppl as any, '_compileMaterial').mockImplementation(() => {});
ppl.activate(null!);
// Ensure EmptyDescriptorSetLayout has descriptorType / bindingIndices populated like WebGL2DescriptorSetLayout
for (const v of lg.v()) {
const set = lg.getLayout(v).getSet(UpdateFrequency.PER_PASS);
if (set?.descriptorSetLayout) {
const dsl = set.descriptorSetLayout;
for (let i = 0; i < dsl.bindings.length; ++i) {
dsl.bindings[i].descriptorType = DescriptorType.UNIFORM_BUFFER;
const b = dsl.bindings[i].binding;
dsl.bindingIndices[b] = i;
dsl.descriptorIndices[b] = i;
}
}
}
(ppl as any)._width = 64;
(ppl as any)._height = 64;
const prevPipeline = cclegacy.director.root.pipeline;
const prevRendering = cclegacy.rendering;
cclegacy.director.root._pipeline = ppl;
cclegacy.rendering = {
getPassID: (name?: string): number => lg.locateChild(lg.N, name || 'default'),
getPhaseID: (): number => defaultStage + 1,
};
ppl.addRenderTarget('Temp0', Format.RGBA8, 64, 64, ResourceResidency.PERSISTENT);
ppl.addRenderTarget('Color0', Format.RGBA8, 64, 64, ResourceResidency.PERSISTENT);
return {
ppl,
stageA,
stageB,
getBoundBuffer: (layoutName: string, binding = bugBinding): Buffer => {
const stageId = lg.locateChild(lg.N, layoutName);
const set = lg.getLayout(stageId).getSet(UpdateFrequency.PER_PASS)!;
return set.descriptorSet!.getBuffer(binding);
},
cleanup: (): void => {
cclegacy.director.root._pipeline = prevPipeline;
cclegacy.rendering = prevRendering;
},
};
}
describe('Custom pipeline per-pass UBO upload', () => {
test('uploads identical uniform values to both passes across 16 alternating frames after default layout warmup', () => {
const tracker = trackUniformBuffers();
const { ppl, stageA, stageB, cleanup, getBoundBuffer } = createUBOTestPipeline(false, true, '-1');
const dummyCam = { viewport: new Rect(0, 0, 1, 1) } as any;
const executor = new Executor(ppl, ppl.device, ppl.resourceGraph, ppl.layoutGraph, 64, 64);
try {
// Warm-up default layout frame
ppl.beginSetup();
const warmPass = ppl.addRenderPass(64, 64, 'default');
warmPass.addRenderTarget('Color0', LoadOp.CLEAR, StoreOp.STORE, new Color(0, 0, 0, 1));
warmPass.addQueue(QueueHint.NONE).addDraw3D(dummyCam, []);
ppl.endSetup();
ppl.compile();
executor.execute(ppl.renderGraph!);
ppl.endFrame();
const val = new Vec4();
for (let frame = 0; frame < 16; ++frame) {
const input = frame & 1;
val.set(input, 0, 0, 0);
ppl.beginSetup();
const passA = ppl.addRenderPass(64, 64, stageA);
passA.addRenderTarget('Temp0', LoadOp.DISCARD, StoreOp.STORE);
passA.setVec4('bugParam', val);
passA.addQueue(QueueHint.NONE).addDraw3D(dummyCam, []);
const passB = ppl.addRenderPass(64, 64, stageB);
passB.addRenderTarget('Color0', LoadOp.DISCARD, StoreOp.STORE);
passB.setVec4('bugParam', val);
passB.addQueue(QueueHint.NONE).addDraw3D(dummyCam, []);
ppl.endSetup();
ppl.compile();
executor.execute(ppl.renderGraph!);
const wordsA = tracker.bufferWords.get(getBoundBuffer(stageA))!;
const wordsB = tracker.bufferWords.get(getBoundBuffer(stageB))!;
const expectedWord = input === 1 ? 0x3f800000 : 0x00000000;
expect(wordsA[0]).toBe(expectedWord);
expect(wordsB[0]).toBe(expectedWord);
ppl.endFrame();
}
} finally {
executor.release();
ppl.destroy();
cleanup();
tracker.restore();
}
});
test('preserves IEEE-754 negative zero sign bit (0x80000000 vs 0x00000000) across alternating frames', () => {
const tracker = trackUniformBuffers();
const { ppl, stageA, stageB, cleanup, getBoundBuffer } = createUBOTestPipeline(false, true, '-2');
const dummyCam = { viewport: new Rect(0, 0, 1, 1) } as any;
const executor = new Executor(ppl, ppl.device, ppl.resourceGraph, ppl.layoutGraph, 64, 64);
try {
const valA = new Vec4(1, 0, 0, 0);
const valB = new Vec4(0, 0, 0, 0);
const observedWordsB: number[] = [];
for (let frame = 0; frame < 8; ++frame) {
valB.x = (frame & 1) === 0 ? +0 : -0;
ppl.beginSetup();
const passA = ppl.addRenderPass(64, 64, stageA);
passA.addRenderTarget('Temp0', LoadOp.DISCARD, StoreOp.STORE);
passA.setVec4('bugParam', valA);
passA.addQueue(QueueHint.NONE).addDraw3D(dummyCam, []);
const passB = ppl.addRenderPass(64, 64, stageB);
passB.addRenderTarget('Color0', LoadOp.DISCARD, StoreOp.STORE);
passB.setVec4('bugParam', valB);
passB.addQueue(QueueHint.NONE).addDraw3D(dummyCam, []);
ppl.endSetup();
ppl.compile();
executor.execute(ppl.renderGraph!);
const wordsB = tracker.bufferWords.get(getBoundBuffer(stageB))!;
observedWordsB.push(wordsB[0]);
ppl.endFrame();
}
expect(observedWordsB).toEqual([
0x00000000,
0x80000000,
0x00000000,
0x80000000,
0x00000000,
0x80000000,
0x00000000,
0x80000000,
]);
} finally {
executor.release();
ppl.destroy();
cleanup();
tracker.restore();
}
});
test('allows queue.setBuffer to override parent pass UBO binding across frames', () => {
const tracker = trackUniformBuffers();
const { ppl, stageA, cleanup, getBoundBuffer } = createUBOTestPipeline(false, true, '-3');
const dummyCam = { viewport: new Rect(0, 0, 1, 1) } as any;
const executor = new Executor(ppl, ppl.device, ppl.resourceGraph, ppl.layoutGraph, 64, 64);
const extBuffer = ppl.device.createBuffer(new BufferInfo(
BufferUsageBit.UNIFORM | BufferUsageBit.TRANSFER_DST,
MemoryUsageBit.HOST | MemoryUsageBit.DEVICE,
16,
16,
));
extBuffer.update(new Float32Array([1.0, 0.5, 0.0, 0.0]));
try {
for (let frame = 0; frame < 4; ++frame) {
ppl.beginSetup();
const pass = ppl.addRenderPass(64, 64, stageA);
pass.addRenderTarget('Color0', LoadOp.CLEAR, StoreOp.STORE);
if (frame >= 1) {
pass.setVec4('bugParam', new Vec4(0, 0, 0, 0));
}
const queue = pass.addQueue(QueueHint.NONE);
queue.setBuffer('BugUBO', extBuffer);
queue.addDraw3D(dummyCam, []);
ppl.endSetup();
ppl.compile();
executor.execute(ppl.renderGraph!);
const bound = getBoundBuffer(stageA);
expect(bound).toBe(extBuffer);
const words = tracker.bufferWords.get(bound)!;
expect(words[0]).toBe(0x3f800000); // 1.0
expect(words[1]).toBe(0x3f000000); // 0.5
ppl.endFrame();
}
} finally {
executor.release();
ppl.destroy();
expect(tracker.bufferWords.has(extBuffer)).toBe(true);
extBuffer.destroy();
cleanup();
tracker.restore();
}
});
test('isolates partial UBO member updates across layouts while preserving pass-to-queue inheritance', () => {
const tracker = trackUniformBuffers();
const { ppl, stageA, stageB, cleanup, getBoundBuffer } = createUBOTestPipeline(true, true, '-5');
const dummyCam = { viewport: new Rect(0, 0, 1, 1) } as any;
const executor = new Executor(ppl, ppl.device, ppl.resourceGraph, ppl.layoutGraph, 64, 64);
try {
for (let frame = 0; frame < 4; ++frame) {
ppl.beginSetup();
// Pass A (stageA): only sets bugParam (fieldX = 0); bugExtra (fieldY) must stay 0 across all frames
const passA = ppl.addRenderPass(64, 64, stageA);
passA.addRenderTarget('Temp0', LoadOp.DISCARD, StoreOp.STORE);
passA.setVec4('bugParam', new Vec4(0, 0, 0, 0));
passA.addQueue(QueueHint.NONE).addDraw3D(dummyCam, []);
// Pass B (stageB): pass sets bugParam = 0.5, queue sets bugExtra = 1.0 (inherits bugParam = 0.5)
const passB = ppl.addRenderPass(64, 64, stageB);
passB.addRenderTarget('Color0', LoadOp.DISCARD, StoreOp.STORE);
passB.setVec4('bugParam', new Vec4(0.5, 0, 0, 0));
const queueB = passB.addQueue(QueueHint.NONE);
queueB.setVec4('bugExtra', new Vec4(1.0, 0, 0, 0));
queueB.addDraw3D(dummyCam, []);
ppl.endSetup();
ppl.compile();
executor.execute(ppl.renderGraph!);
const wordsA = tracker.bufferWords.get(getBoundBuffer(stageA))!;
const wordsB = tracker.bufferWords.get(getBoundBuffer(stageB))!;
// Pass A: bugParam.x = 0, bugExtra.x = 0 (not polluted by Pass B's bugExtra = 1.0)
expect(wordsA[0]).toBe(0x00000000);
expect(wordsA[4]).toBe(0x00000000);
// Pass B: queue inherited bugParam.x = 0.5 (0x3f000000) and applied bugExtra.x = 1.0 (0x3f800000)
expect(wordsB[0]).toBe(0x3f000000);
expect(wordsB[4]).toBe(0x3f800000);
ppl.endFrame();
}
} finally {
executor.release();
ppl.destroy();
cleanup();
tracker.restore();
}
});
test('reuses bound GPU buffer across 128 queues writing identical 32-byte UBO and frees buffers on pipeline.destroy()', () => {
const tracker = trackUniformBuffers();
const { ppl, stageA, cleanup } = createUBOTestPipeline(true, false, '-4');
const dummyCam = { viewport: new Rect(0, 0, 1, 1) } as any;
const executor = new Executor(ppl, ppl.device, ppl.resourceGraph, ppl.layoutGraph, 64, 64);
const baselineBytes = tracker.liveBytes;
const runFrameWithQueues = (queueCount: number, distinctPerQueue = false): void => {
ppl.beginSetup();
const pass = ppl.addRenderPass(64, 64, stageA);
pass.addRenderTarget('Color0', LoadOp.CLEAR, StoreOp.STORE);
for (let i = 0; i < queueCount; ++i) {
const q = pass.addQueue(QueueHint.NONE);
q.setVec4('bugParam', new Vec4(distinctPerQueue ? i : 1, 2, 3, 4));
q.setVec4('bugExtra', new Vec4(5, 6, 7, 8));
q.addDraw3D(dummyCam, []);
}
ppl.endSetup();
ppl.compile();
executor.execute(ppl.renderGraph!);
ppl.endFrame();
};
try {
// 1 queue writing 32-byte UBO -> 1 DescBuffManager = 2 * 32 = 64 bytes
runFrameWithQueues(1, false);
expect(tracker.liveBytes - baselineBytes).toBe(64);
// 128 queues writing the SAME 32-byte UBO -> 0 extra bytes (NOT +8128 bytes)
runFrameWithQueues(128, false);
expect(tracker.liveBytes - baselineBytes).toBe(64);
// Recover to 1 queue -> still 64 bytes
runFrameWithQueues(1, false);
expect(tracker.liveBytes - baselineBytes).toBe(64);
// Even if 128 temporary queues write DISTINCT 32-byte UBOs, pipeline.destroy() frees all buffers
runFrameWithQueues(128, true);
expect(tracker.liveBytes - baselineBytes).toBe(64 + 8128);
// Destroying pipeline frees all UBO GPU buffers
ppl.destroy();
expect(tracker.liveBytes - baselineBytes).toBe(0);
} finally {
cleanup();
tracker.restore();
}
});
});