diff --git a/EngineErrorMap.md b/EngineErrorMap.md index 1469eec28c..6efa3036ac 100644 --- a/EngineErrorMap.md +++ b/EngineErrorMap.md @@ -3205,6 +3205,38 @@ request fullscreen is not supported on this platform. exit fullscreen is not supported on this platform. +### 9010 + +UIMesh.setMeshData: unsupported vertexStride %d, expected %d (V3F_T2F_C4B) or %d (V3F_T2F_C4B_C4B); data rejected. + +### 9011 + +UIMesh.setMeshData: negative counts (vertexCount %d, indexCount %d); data rejected. + +### 9012 + +UIMesh.setMeshData: vertexData holds %d bytes, but %d vertices x %d bytes are declared; data rejected. + +### 9013 + +UIMesh.setMeshData: indexData is %d bytes at offset %d, but %d Uint16 indices need %d bytes (2-byte aligned view); data rejected. + +### 9014 + +UIMesh.setMeshData: indices[%d] = %d is out of range for %d vertices; data rejected. + +### 9015 + +UIMesh.setMeshData: segment %d range [%d, %d) is out of bounds for indexCount %d; data rejected. + +### 9016 + +UIMesh.setMeshData: %d vertices / %d indices exceed the accessor cap (%d / %d); split the mesh. Data rejected. + +### 9017 + +UIMesh: render data allocation failed for %d vertices / %d indices (accessor cap: %d / %d). + ### 9100 texture size exceeds current device limits %d/%d diff --git a/cc.config.json b/cc.config.json index 990c996a62..6078cae854 100644 --- a/cc.config.json +++ b/cc.config.json @@ -307,6 +307,9 @@ "worker-pool": { "modules": ["worker", "worker-pool"], "dependentModules": ["worker"] + }, + "webassembly": { + "modules": ["webassembly"] } }, "moduleOverrides": [{ diff --git a/cocos/2d/components/index.ts b/cocos/2d/components/index.ts index 9394a45c0c..649e413782 100644 --- a/cocos/2d/components/index.ts +++ b/cocos/2d/components/index.ts @@ -25,6 +25,7 @@ export * from './label'; export { Sprite } from './sprite'; export { UIMeshRenderer } from './ui-mesh-renderer'; +export * from './ui-mesh'; export { LabelOutline } from './label-outline'; export { UIStaticBatch } from './ui-static-batch'; export { LabelShadow } from './label-shadow'; diff --git a/cocos/2d/components/ui-mesh.ts b/cocos/2d/components/ui-mesh.ts new file mode 100644 index 0000000000..0aad571a41 --- /dev/null +++ b/cocos/2d/components/ui-mesh.ts @@ -0,0 +1,636 @@ +/* + Copyright (c) 2026 + Generic 2D mesh data consumer: the plugin feeds pre-baked vertex/index/segment + data through setMeshData; this component owns buffer allocation, batching and + submission through the 2D batcher, so extensions can render custom meshes + without touching engine internals. + + Vertices are ALWAYS node-local; UIMesh owns the node transform: + * not batched -- on the GPU, via USE_LOCAL + the per-draw cc-local UBO the + batcher already maintains for middleware draws; + * batched -- the FULL world matrix baked into the chunk copy on the CPU + (a merged batch carries no per-draw matrix), matching the GPU path, z / + X-Y rotation included. + USE_LOCAL / setUseLocal are derived internally; there is no world-baked + input mode. + + Data is FillColorType.VERTEX, so the batcher applies no cascaded opacity: + UIMesh folds it into the copied vertices itself, accumulated as Batcher2D.walk + does for COLOR data (own color alpha x, per ancestor, UIOpacity localOpacity x + that ancestor's color alpha). `premultipliedAlpha` declares the data format: + alpha-byte-only vs RGBA + dark RGB fading. + + The batcher resets the shared index tail after every upload (vertex bytes + survive), so indices are re-submitted EVERY frame (appendIndexBuffer) and only + the vertex refresh is _vertexDirty-gated. A dirty-gated submission would leave + a static mesh's draw range aliasing whichever sibling appends after the reset + (two UIMeshes in one buffer, one paused: it would draw the other's triangles). +*/ + +import { JSB } from 'internal:constants'; +import { ccclass, editable, serializable } from 'cc.decorator'; +import { errorID } from '../../core'; +import { Mat4 } from '../../core/math'; +import { UIRenderer } from '../framework/ui-renderer'; +import { RenderData } from '../renderer/render-data'; +import { RenderDrawInfo, RenderDrawInfoType } from '../renderer/render-draw-info'; +import { StaticVBAccessor } from '../renderer/static-vb-accessor'; +import type { Batcher2D } from '../renderer/batcher-2d'; +import { vfmtPosUvColor4B, vfmtPosUvTwoColor4B, getAttributeStride } from '../renderer/vertex-format'; +import { RenderEntity, RenderEntityType } from '../renderer/render-entity'; +import { director, DirectorEvent } from '../../game'; +import { Texture2D } from '../../asset/assets'; +import { builtinResMgr } from '../../asset/asset-manager'; +import { BlendFactor } from '../../gfx'; +import type { MeshBuffer } from '../renderer/mesh-buffer'; +import type { MaterialInstance } from '../../render-scene'; +import type { Material } from '../../asset/assets/material'; +import type { Node } from '../../scene-graph'; + +/** + * @en A segment of the mesh: a range of indices drawn with one texture+material. + * @zh 网格的一个片段:一段索引,用同一纹理+材质绘制。 + */ +export interface UIMeshSegment { + indexOffset: number; + indexCount: number; + texture: Texture2D | null; + material: MaterialInstance | null; +} + +/** + * @en Pre-baked mesh data for one frame. + * @zh 一帧的预烘焙网格数据。 + * vertexStride: 24 (single-color V3F_T2F_C4B) or 28 (two-color V3F_T2F_C4B_C4B). + */ +export interface UIMeshData { + vertexCount: number; + vertexStride: number; + vertexData: Uint8Array; + indexCount: number; + indexData: Uint8Array; + segments: UIMeshSegment[]; +} + +// Shared static vertex-buffer accessors, keyed by the current Batcher2D: it +// destroys every accessor registered with it, so a rebuilt root must never +// reuse a cached (destroyed) accessor, and each new one must be registered +// with the current batcher or its buffers would never be uploaded or reset. +let _accessorBatcher: Batcher2D | null = null; +let _sharedAccessor: StaticVBAccessor | null = null; +let _sharedTintAccessor: StaticVBAccessor | null = null; + +// Registration keys in the batcher's accessor map (base-36 namespaced, the +// same convention as the built-in middleware assemblers — spine/dragon-bones). +const UIMESH_ACCESSOR_KEY = Number.parseInt('UIMESH', 36); +const UIMESH_TINT_ACCESSOR_KEY = Number.parseInt('UIMESHTINT', 36); + +// The two consumed vertex formats (24 / 28 bytes); strides derived from the +// definitions so the byte math always matches the chunk's format. +const MESH_STRIDE_BYTES = getAttributeStride(vfmtPosUvColor4B); +const MESH_STRIDE_TINT_BYTES = getAttributeStride(vfmtPosUvTwoColor4B); + +/** + * @en A generic 2D mesh renderer that consumes pre-baked vertex/index data. + * The data provider (e.g. a spine plugin) fills setMeshData every frame; this + * component handles buffer allocation, batching and submission. + * @zh 通用 2D 网格渲染器,消费预烘焙的顶点/索引数据。数据提供方(如 spine 插件) + * 每帧调用 setMeshData,本组件负责缓冲分配、合批与提交。 + */ +@ccclass('cc.UIMesh') +export class UIMesh extends UIRenderer { + @serializable + protected _enableBatch = false; + + /** + * @en Whether the incoming color data is premultiplied-alpha. Declares how + * cascaded opacity is folded into the vertices (alpha byte only vs + * RGBA + dark RGB) and the blend factors of the builtin material. + * @zh 输入颜色数据是否为预乘 alpha 格式。决定级联不透明度折算方式 + * (仅 alpha 字节 vs RGBA + dark RGB)及内置材质混合因子。 + */ + @serializable + protected _premultipliedAlpha = false; + + protected _meshData: UIMeshData | null = null; + protected _useTint = false; + private _drawInfoList: RenderDrawInfo[] = []; + + // Poll cache (see _onBeforeDraw): inputs captured by the last + // updateVertexBuffer run; drift means the baked transform / folded opacity + // no longer match. The full matrix is tracked — the bake applies all of it. + private _pollOpacity = 1; + private _pollWorldMatrix = new Mat4(); + + // Vertex-staleness latch, consumed by _onBeforeDraw to pick a full refresh + // vs an index-only resubmit. Starts dirty so the first frame prepares. + private _vertexDirty = true; + + constructor () { + super(); + this._useVertexOpacity = true; + } + + /** + * @en Feeds the pre-baked mesh data for the current frame. + * @zh 喂入当前帧的预烘焙网格数据。 + */ + public setMeshData (data: UIMeshData): void { + // Reject bad input at the call site; a rejected frame keeps the last + // accepted mesh. + if (!this._validateMeshData(data)) return; + const useTint = data.vertexStride === MESH_STRIDE_TINT_BYTES; + if (useTint !== this._useTint) { + this.destroyRenderData(); + this._useTint = useTint; + this._flushAssembler(); + // The builtin fallback material follows the stride (TWO_COLORED). + this.updateMaterial(); + } + this._meshData = data; + this._vertexDirty = true; + } + + private _validateMeshData (data: UIMeshData): boolean { + const vc = data.vertexCount; + const ic = data.indexCount; + if (data.vertexStride !== MESH_STRIDE_BYTES && data.vertexStride !== MESH_STRIDE_TINT_BYTES) { + errorID(9010, data.vertexStride, MESH_STRIDE_BYTES, MESH_STRIDE_TINT_BYTES); + return false; + } + if (vc < 0 || ic < 0) { + errorID(9011, vc, ic); + return false; + } + // Capacity limits come from the accessor that will serve the data. + const accessor = this.ensureAccessor(data.vertexStride === MESH_STRIDE_TINT_BYTES); + if (vc > accessor.maxVertexCount || ic > accessor.maxIndexCount) { + errorID(9016, vc, ic, accessor.maxVertexCount, accessor.maxIndexCount); + return false; + } + if (!data.vertexData || data.vertexData.byteLength < vc * data.vertexStride) { + errorID(9012, data.vertexData ? data.vertexData.byteLength : 0, vc, data.vertexStride); + return false; + } + if (!data.indexData || data.indexData.byteOffset % 2 !== 0 || data.indexData.byteLength < ic * 2) { + errorID( + 9013, + data.indexData ? data.indexData.byteLength : 0, + data.indexData ? data.indexData.byteOffset : 0, + ic, + ic * 2, + ); + return false; + } + // Indices are mesh-local; anything >= vertexCount would sample vertices + // of other chunks in the shared buffer (silent geometry corruption). + const indices = new Uint16Array(data.indexData.buffer, data.indexData.byteOffset, ic); + for (let i = 0; i < ic; ++i) { + if (indices[i] >= vc) { + errorID(9014, i, indices[i], vc); + return false; + } + } + for (let i = 0; i < data.segments.length; ++i) { + const seg = data.segments[i]; + if (seg.indexOffset < 0 || seg.indexCount < 0 || seg.indexOffset + seg.indexCount > ic) { + errorID(9015, i, seg.indexOffset, seg.indexOffset + seg.indexCount, ic); + return false; + } + } + return true; + } + + /** + * @en Whether to enable sprite batching. + * @zh 是否启用合批。 + */ + @editable + get enableBatch (): boolean { return this._enableBatch; } + set enableBatch (value: boolean) { + this._enableBatch = value; + this._syncTransformMode(); + this.updateMaterial(); + } + + /** + * @en Whether the input color data is premultiplied-alpha. + * @zh 输入颜色数据是否为预乘 alpha 格式。 + */ + @editable + get premultipliedAlpha (): boolean { return this._premultipliedAlpha; } + set premultipliedAlpha (value: boolean) { + this._premultipliedAlpha = value; + this.updateMaterial(); + this._vertexDirty = true; + this.onPremultipliedAlphaChanged(); + } + + /** + * Notifies subclasses the declared format changed. The property is owned + * here (single source of truth); producers override this to forward it to + * their baker instead of redeclaring the field. + */ + protected onPremultipliedAlphaChanged (): void {} + + public onLoad (): void { + super.onLoad(); + // Deserialization has applied _enableBatch by now; re-derive the + // legacy switch state. + this._syncTransformMode(); + } + + /** + * useLocal == "vertices are still node-local at submit time". Batched data + * is world-baked by updateVertexBuffer before submit, and native + * middleware draws only merge when !useLocal — hence !enableBatch. + */ + private _syncTransformMode (): void { + this._renderEntity.setUseLocal(!this._enableBatch); + this._vertexDirty = true; + } + + protected _updateColor (): void { + super._updateColor(); + // The opacity fold in updateVertexBuffer reads this._color, so a + // change must re-prepare. Visibility (color.a 0 <-> !0) is recomputed + // fresh by _onBeforeDraw. + this._vertexDirty = true; + } + + protected _onMaterialModified (idx: number, material: Material | null): void { + super._onMaterialModified(idx, material); + // Draw infos cache the material reference; a swap must rebuild them. + // The base mark only re-syncs visibility (no updateRenderer override + // anymore), and the passDirty self-heal path needs an assembler. + this._vertexDirty = true; + } + + public onEnable (): void { + super.onEnable(); + // BEFORE_DRAW fires between the update and render phases, outside the + // director.pause() gate — the render loop still redraws (and resets + // shared buffers) while paused, so submission must keep running. + if (JSB) director.on(DirectorEvent.BEFORE_DRAW, this._onBeforeDraw, this); + } + + public onDisable (): void { + if (JSB) director.off(DirectorEvent.BEFORE_DRAW, this._onBeforeDraw, this); + super.onDisable(); + } + + /** + * JSB per-frame driver (director BEFORE_DRAW); web is driven by fillBuffers + * instead. Three jobs: + * * poll — transforms / UIOpacity never mark a middleware renderer, so + * compare the live values against the last updateVertexBuffer capture; + * * visibility — recomputed fresh (the base class' synchronous + * _updateColor recompute is assembler-gated, dead here); an invisible + * mesh submits nothing and its draw infos are cleared; + * * data — full refresh when the latch is set or the mesh just became + * visible again, else the frame-scoped appendIndexBuffer only. + */ + private _onBeforeDraw (): void { + if (!JSB || !this._renderData || !this._meshData) return; + if (this._enableBatch && !this.node.worldMatrix.strictEquals(this._pollWorldMatrix)) { + this._vertexDirty = true; + } + if (this._computeCascadedOpacity() !== this._pollOpacity) { + this._vertexDirty = true; + } + const wasRenderable = this._renderFlag; + const canRender = this._canRender(); + this._renderFlag = canRender; + this._renderEntity.enabled = canRender; + if (!canRender) { + if (wasRenderable) this._renderEntity.clearDynamicRenderDrawInfos(); + return; + } + if (this._vertexDirty || !wasRenderable) { + this._prepareNativeDrawInfos(); + this._vertexDirty = false; + } else { + this.appendIndexBuffer(); + } + } + + protected _flushAssembler (): void { + if (this._renderData === null) { + const accessor = this.ensureAccessor(this._useTint); + this._renderData = RenderData.add(this._useTint ? vfmtPosUvTwoColor4B : vfmtPosUvColor4B, accessor); + } + } + + protected _render (batcher: any): void { + const prepared = this._prepareBuffers(); + if (!prepared || !this._meshData) return; + const { meshBuffer, startIndex } = prepared; + const data = this._meshData; + + // Segments without their own material fall back to the component + // material (the builtin spine effect). + for (const seg of data.segments) { + const mat = seg.material || this.getRenderMaterial(0); + if (seg.texture && mat) { + batcher.commitMiddleware( + this, + meshBuffer, + startIndex + seg.indexOffset, + seg.indexCount, + seg.texture, + mat, + this._enableBatch, + ); + } + } + } + + private _prepareBuffers (): { meshBuffer: MeshBuffer, startIndex: number } | null { + // Full refresh: the dirty-gated vertex half + the frame-scoped index + // half. Shared by the web walk (_render) and _prepareNativeDrawInfos. + if (!this.updateVertexBuffer()) return null; + return this.appendIndexBuffer(); + } + + /** + * Vertex half of a refresh: grow the chunk, copy this frame's bytes, bake + * the world matrix when batching, fold cascaded opacity, capture the poll + * inputs. The expensive half — callers gate it (native: dirty only; web: + * every frame). Returns whether the chunk holds this frame's vertices. + */ + protected updateVertexBuffer (): boolean { + if (!this._renderData || !this._meshData) return false; + const data = this._meshData; + const rd = this._renderData; + const vc = data.vertexCount; + const ic = data.indexCount; + if (vc < 1 || ic < 1) return false; + const vLength = vc * data.vertexStride; + + // ~10% head room, clamped to the accessor's per-chunk caps — an + // unclamped reserve would permanently fail data that fits (30000 -> + // 33000 requested > 32767). Per-frame counts live on the render data; + // the reserve lives on the chunk. + if (!rd.chunk || rd.chunk.vb.byteLength < vLength || rd.chunk.indexCount < ic) { + rd.resize( + Math.min(Math.ceil(vc * 1.1), rd.accessor.maxVertexCount), + Math.min(Math.ceil(ic * 1.1), rd.accessor.maxIndexCount), + ); + if (!rd.chunk) { + errorID(9017, vc, ic, rd.accessor.maxVertexCount, rd.accessor.maxIndexCount); + return false; + } + rd.updateSize(vc, ic); + } else if (rd.vertexCount !== vc || rd.indexCount !== ic) { + rd.updateSize(vc, ic); + } + if (!rd.chunk) return false; + // Copy into the chunk's view of the shared vData. + const vbuf = rd.chunk.vb; + const vU8 = new Uint8Array(vbuf.buffer, vbuf.byteOffset, vLength); + vU8.set(data.vertexData.subarray(0, vLength)); + + // Batched: a merged batch carries no per-draw matrix, so bake the + // world transform into the chunk copy (the incoming vertexData may be + // a worker-shared view — never touch it). + if (this._enableBatch) { + this._bakeWorldTransform(vbuf, vLength, data.vertexStride); + } + + // Cascaded opacity: VERTEX-type data gets no engine-side fade, UIMesh + // applies it while copying (see the opacity contract in the header). + const opacity = this._computeCascadedOpacity(); + if (opacity < 0.9999) { + this._applyOpacity(vU8, vc, data.vertexStride, opacity); + } + + // Capture the poll inputs (compared in _onBeforeDraw). + this._pollOpacity = opacity; + if (this._enableBatch) { + this._pollWorldMatrix.set(this.node.worldMatrix); + } + return true; + } + + /** + * Index half: offset by the chunk's vertexOffset, append into the shared + * index buffer, refresh the draw-info offsets. Must run EVERY frame for + * every participating mesh — the batcher resets the index tail after each + * upload while draw infos keep absolute offsets, so a mesh that skipped + * would alias whichever sibling appends first (see the header contract). + * Runs exactly once per frame (native pump / web fillBuffers); + * commitMiddleware reads meshBuffer.iData. + */ + protected appendIndexBuffer (): { meshBuffer: MeshBuffer, startIndex: number } | null { + const data = this._meshData; + const rd = this._renderData; + if (!rd || !rd.chunk || !data || data.vertexCount < 1 || data.indexCount < 1) { + return null; + } + const meshBuffer = rd.getMeshBuffer()!; + // The native batcher resets indexOffset through shared memory after + // uploading — sync the JS-side cache before appending. + if (JSB) meshBuffer.indexOffset = meshBuffer.sharedBuffer[2]; + const startIndex = meshBuffer.indexOffset; + const ic = data.indexCount; + const chunkOffset = rd.chunk.vertexOffset; + const offsetIndices = new Uint16Array(ic); + new Uint8Array(offsetIndices.buffer).set(data.indexData.subarray(0, ic * 2)); + for (let i = 0; i < ic; i++) offsetIndices[i] += chunkOffset; + rd.chunk.vertexAccessor.appendIndices(rd.chunk.bufferId, offsetIndices); + rd.chunk.vertexAccessor.getMeshBuffer(rd.chunk.bufferId).setDirty(); + + // Static frames never re-run _prepareNativeDrawInfos — keep the cached + // draw infos' offsets in step (segment mapping mirrors it). + this._refreshDrawInfoOffsets(startIndex); + return { meshBuffer, startIndex }; + } + + private _refreshDrawInfoOffsets (startIndex: number): void { + const data = this._meshData; + if (!data || this._drawInfoList.length === 0) return; + let drawIndex = 0; + for (const seg of data.segments) { + const mat = seg.material || this.getRenderMaterial(0); + if (!seg.texture || !mat) continue; + const drawInfo = this._drawInfoList[drawIndex++]; + if (drawInfo) drawInfo.setIndexOffset(startIndex + seg.indexOffset); + } + } + + /** + * Bakes the FULL world matrix into the chunk copy's positions — exactly + * what the USE_LOCAL GPU path applies (pos = cc_matWorld * pos), z and + * X/Y-rotation included, so batched and unbatched renders agree. Identity + * is skipped. + */ + private _bakeWorldTransform (vbuf: Float32Array, byteLength: number, stride: number): void { + const m = this.node.worldMatrix; + const m00 = m.m00; const m01 = m.m01; const m02 = m.m02; + const m04 = m.m04; const m05 = m.m05; const m06 = m.m06; + const m08 = m.m08; const m09 = m.m09; const m10 = m.m10; + const m12 = m.m12; const m13 = m.m13; const m14 = m.m14; + if (m00 === 1 && m01 === 0 && m02 === 0 + && m04 === 0 && m05 === 1 && m06 === 0 + && m08 === 0 && m09 === 0 && m10 === 1 + && m12 === 0 && m13 === 0 && m14 === 0) return; + const floats = new Float32Array(vbuf.buffer, vbuf.byteOffset, byteLength >> 2); + const strideF = stride >> 2; + const vertexCount = byteLength / stride; + for (let i = 0; i < vertexCount; i++) { + const o = i * strideF; + const x = floats[o]; + const y = floats[o + 1]; + const z = floats[o + 2]; + floats[o] = m00 * x + m04 * y + m08 * z + m12; + floats[o + 1] = m01 * x + m05 * y + m09 * z + m13; + floats[o + 2] = m02 * x + m06 * y + m10 * z + m14; + } + } + + /** + * Cascaded opacity as Batcher2D.walk accumulates it for COLOR data: own + * color alpha x, per ancestor, localOpacity x that ancestor's color alpha. + */ + private _computeCascadedOpacity (): number { + let opacity = this._color.a / 255; + for (let node: Node | null = this.node; node; node = node.parent) { + opacity *= node._uiProps.localOpacity; + if (node !== this.node) { + const ancestor = node._uiProps.uiComp as UIRenderer | null; + if (ancestor && ancestor.color) opacity *= ancestor.color.a / 255; + } + } + return opacity; + } + + /** + * Folds opacity into the copied vertices. Light color sits at bytes + * 20..23 (pos*3f + uv*2f), dark at 24..27 for two-color. Straight data + * fades via the alpha byte only; PMA data scales light RGBA + dark RGB + * (dark alpha is the sentinel, not a fade channel). + */ + private _applyOpacity (vU8: Uint8Array, vc: number, stride: number, opacity: number): void { + const pma = this._premultipliedAlpha; + const darkRGB = (pma && stride === MESH_STRIDE_TINT_BYTES) ? 3 : 0; + for (let i = 0; i < vc; i++) { + const o = i * stride + 20; + if (pma) { + vU8[o] = (vU8[o] * opacity + 0.5) | 0; + vU8[o + 1] = (vU8[o + 1] * opacity + 0.5) | 0; + vU8[o + 2] = (vU8[o + 2] * opacity + 0.5) | 0; + } + vU8[o + 3] = (vU8[o + 3] * opacity + 0.5) | 0; + for (let j = 0; j < darkRGB; j++) { + vU8[o + 4 + j] = (vU8[o + 4 + j] * opacity + 0.5) | 0; + } + } + } + + private _prepareNativeDrawInfos (): void { + this._renderEntity.clearDynamicRenderDrawInfos(); + // Vertex refresh + this frame's index submission; a null return means + // there is nothing drawable this frame. + const prepared = this._prepareBuffers(); + const data = this._meshData; + const rd = this._renderData; + if (!prepared || !data || !rd?.chunk) return; + + const { startIndex } = prepared; + let drawIndex = 0; + for (const seg of data.segments) { + const mat = seg.material || this.getRenderMaterial(0); + if (!seg.texture || !mat) continue; + let drawInfo = this._drawInfoList[drawIndex]; + if (!drawInfo) { + drawInfo = new RenderDrawInfo(); + drawInfo.setDrawInfoType(RenderDrawInfoType.MIDDLEWARE); + this._drawInfoList[drawIndex] = drawInfo; + } + drawInfo.setAccAndBuffer(rd.accessor.id, rd.chunk.bufferId); + drawInfo.setIndexOffset(startIndex + seg.indexOffset); + drawInfo.setIBCount(seg.indexCount); + drawInfo.setTexture(seg.texture.getGFXTexture()); + drawInfo.setSampler(seg.texture.getGFXSampler()); + drawInfo.setMaterial(mat); + this._renderEntity.setDynamicRenderDrawInfo(drawInfo, drawIndex); + drawIndex++; + } + } + + /** + * The spine effect (default-spine-material): ui-sprite-material has no + * USE_LOCAL variant — node-local input through it would render stuck at + * the origin. + */ + protected _updateBuiltinMaterial (): Material { + return builtinResMgr.get('default-spine-material'); + } + + /** + * Keeps the builtin material instance in step with the declared vertex + * space / data format: USE_LOCAL for the GPU take-over mode, TWO_COLORED + * for two-color data, and blend factors matching the alpha format. + */ + public updateMaterial (): void { + // Align the legacy blend-factor fields first so _updateBlendFunc + // (inside super) never fights the explicit patching below. + this._srcBlendFactor = this._premultipliedAlpha ? BlendFactor.ONE : BlendFactor.SRC_ALPHA; + this._dstBlendFactor = BlendFactor.ONE_MINUS_SRC_ALPHA; + super.updateMaterial(); + if (this._customMaterial) return; // custom materials are the user's contract + const inst = this.getMaterialInstance(0); + if (!inst) return; + inst.recompileShaders({ + USE_LOCAL: !this._enableBatch, + TWO_COLORED: this._useTint, + }); + // Straight data: src_alpha / 1-src_alpha (the effect default); + // premultiplied data: ONE / 1-src_alpha, color and alpha channels. + const src = this._premultipliedAlpha ? BlendFactor.ONE : BlendFactor.SRC_ALPHA; + const pass = inst.passes[0]; + const target = pass.blendState.targets[0]; + target.blend = true; + target.blendSrc = src; + target.blendSrcAlpha = src; + target.blendDst = BlendFactor.ONE_MINUS_SRC_ALPHA; + target.blendDstAlpha = BlendFactor.ONE_MINUS_SRC_ALPHA; + pass.blendState.setTarget(0, target); + pass._updatePassHash(); + } + + protected createRenderEntity (): RenderEntity { + const entity = new RenderEntity(RenderEntityType.DYNAMIC); + // useLocal is re-derived in _syncTransformMode once deserialization + // has run. + entity.setUseLocal(!this._enableBatch); + return entity; + } + + private ensureAccessor (useTint: boolean): StaticVBAccessor { + const batcher = director.root!.batcher2D; + // The previous batcher destroyed its accessors — invalidate the cache. + if (_accessorBatcher !== batcher) { + _accessorBatcher = batcher; + _sharedAccessor = null; + _sharedTintAccessor = null; + } + let accessor = useTint ? _sharedTintAccessor : _sharedAccessor; + if (!accessor) { + const device = director.root!.device; + // Copy the format: the accessor empties its attributes array on + // destroy, and the vfmt* constants are shared module-level state. + const attributes = (useTint ? vfmtPosUvTwoColor4B : vfmtPosUvColor4B).slice(); + // 32767: the spine middleware assembler's per-chunk cap + // (cocos/spine/assembler/simple.ts), half the Uint16 index space. + accessor = new StaticVBAccessor(device, attributes, 32767); + batcher.registerBufferAccessor(useTint ? UIMESH_TINT_ACCESSOR_KEY : UIMESH_ACCESSOR_KEY, accessor); + if (useTint) { + _sharedTintAccessor = accessor; + } else { + _sharedAccessor = accessor; + } + } + return accessor; + } +} diff --git a/cocos/2d/renderer/static-vb-accessor.ts b/cocos/2d/renderer/static-vb-accessor.ts index 7773a7d0b8..cdd6522797 100644 --- a/cocos/2d/renderer/static-vb-accessor.ts +++ b/cocos/2d/renderer/static-vb-accessor.ts @@ -85,6 +85,12 @@ export class StaticVBAccessor extends BufferAccessor { private _id = 0; get id (): number { return this._id; } + /** Per-chunk capacity; allocateChunk refuses requests above these. */ + get maxVertexCount (): number { return this._vCount; } + + /** Per-chunk index capacity; allocateChunk refuses requests above these. */ + get maxIndexCount (): number { return this._iCount; } + public constructor (device: Device, attributes: Attribute[], vCount?: number, iCount?: number) { super(device, attributes); this._vCount = vCount || Math.floor(macro.BATCHER2D_MEM_INCREMENT * 1024 / this._vertexFormatBytes); diff --git a/editor/engine-features/render-config.json b/editor/engine-features/render-config.json index ca18a37631..c961688f30 100644 --- a/editor/engine-features/render-config.json +++ b/editor/engine-features/render-config.json @@ -412,7 +412,7 @@ "spine-3.8": { "enginePlugin": true, "cmakeConfig": "USE_SPINE_3_8", - "default": true, + "default": false, "isNativeModule": true, "label": "i18n:ENGINE.features.spine_38.label", "description": "i18n:ENGINE.features.spine_38.description", @@ -504,6 +504,13 @@ "description": "i18n:ENGINE.features.xr.description", "enginePlugin": false, "envCondition": "$NATIVE || $HTML5" + }, + "webassembly": { + "default": true, + "required": true, + "label": "WebAssembly", + "description": "Export the engine's cross-platform WebAssembly loading interface as cc.wasm, so that extensions and game scripts can load their own .wasm files. 以 cc.wasm 导出引擎的跨平台 WebAssembly 加载接口,供扩展与游戏脚本加载自己的 .wasm 文件。", + "enginePlugin": true } }, "categories": { diff --git a/editor/inspector/assets/texture/parse-atlas.js b/editor/inspector/assets/texture/parse-atlas.js index e843f55ce3..3aa331b3ff 100644 --- a/editor/inspector/assets/texture/parse-atlas.js +++ b/editor/inspector/assets/texture/parse-atlas.js @@ -42,7 +42,7 @@ function formatValue(value) { } const imageExt = ['.png', '.jpg', '.jpeg', '.webp', '.gif']; -const pageAttr = ['name', 'size', 'format', 'filter', 'repeat', 'pma']; +const pageAttr = ['name', 'size', 'format', 'filter', 'repeat', 'scale', 'pma']; class ParseAtlasFile { constructor() { } diff --git a/exports/webassembly.ts b/exports/webassembly.ts new file mode 100644 index 0000000000..781629741f --- /dev/null +++ b/exports/webassembly.ts @@ -0,0 +1,52 @@ +/* + Copyright (c) 2026 Xiamen Yaji Software Co., Ltd. + + https://www.cocos.com/ + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is furnished + to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in + all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + THE SOFTWARE. +*/ + +import { instantiateWasm, fetchBuffer, fetchUrl, ensureWasmModuleReady } from 'pal/wasm'; + +/** + * @en + * The engine's packaged cross-platform WebAssembly interface (pal/wasm). + * + * Re-exported under the public `cc.wasm` namespace so extension/game code can + * load its own `.wasm` files through the same platform-adaptive path the engine + * uses internally for box2d / physx / spine / webgpu: + * + * - web: fetch the `.wasm` bytes, then `WebAssembly.instantiate`; + * - mini-game: resolve the path into `cocos-js/` and delegate to the platform's + * `CCWebAssembly.instantiate` (which accepts a file path, never + * raw bytes — this is why embedded-base64 wasm fails there); + * - native: read the file from `src/cocos-js/` via `fileUtils`. + * + * The `wasmUrl` argument is a bare file name (e.g. `'foo.wasm'`) whose file is + * expected to land in the build output's `cocos-js/` directory. + * @zh + * 引擎封装好的跨平台 WebAssembly 接口(pal/wasm),通过 `cc.wasm` 命名空间公开, + * 供扩展/游戏代码用与引擎内部一致的路径加载自己的 `.wasm`。 + */ +export const wasm = { + instantiateWasm, + fetchBuffer, + fetchUrl, + ensureWasmModuleReady, +}; diff --git a/native/tools/simulator/frameworks/runtime-src/CMakeLists.txt b/native/tools/simulator/frameworks/runtime-src/CMakeLists.txt index e05aa92c7e..be16d44e17 100644 --- a/native/tools/simulator/frameworks/runtime-src/CMakeLists.txt +++ b/native/tools/simulator/frameworks/runtime-src/CMakeLists.txt @@ -43,6 +43,19 @@ set(USE_DEBUG_RENDERER OFF) include(${cocosdir}/CMakeLists.txt) include(${cocosdir}/tools/simulator/libsimulator/CMakeLists.txt) +# Native plugin discovery, same mechanism as native builds. Opt-in: pass +# -DSIMULATOR_PLUGIN_SCAN_DIRS="[;]" with directories to scan for +# cc_plugin.json. Unset (default) keeps the stock plugin-less simulator. +set(SIMULATOR_PLUGIN_SCAN_DIRS "" CACHE STRING + "Directories scanned for cc_plugin.json native plugins") +set(COCOS_X_PATH ${cocosdir}) +if(SIMULATOR_PLUGIN_SCAN_DIRS) + set(CC_PROJECT_DIR ${CMAKE_BINARY_DIR}/plugin-scan) + set(CC_PLUGIN_PATH ${SIMULATOR_PLUGIN_SCAN_DIRS}) + file(MAKE_DIRECTORY ${CC_PROJECT_DIR}) + cc_common_before_target(${APP_NAME}) +endif() + if(MACOSX) @@ -153,6 +166,11 @@ else() endif() target_link_libraries(${LIB_NAME} ${ENGINE_NAME} simulator) +# Plain signature, matching the call above: mixing keyword/plain forms for one +# target is a hard CMake error. +if(TARGET plugin_registry) + target_link_libraries(${LIB_NAME} plugin_registry) +endif() target_include_directories(${LIB_NAME} PRIVATE Classes ) diff --git a/native/tools/simulator/frameworks/runtime-src/Classes/Game.cpp b/native/tools/simulator/frameworks/runtime-src/Classes/Game.cpp index 137e6ff956..e1fc7e6da2 100644 --- a/native/tools/simulator/frameworks/runtime-src/Classes/Game.cpp +++ b/native/tools/simulator/frameworks/runtime-src/Classes/Game.cpp @@ -25,6 +25,7 @@ #include "Game.h" #include "cocos/application/ApplicationManager.h" #include "cocos/bindings/jswrapper/SeApi.h" +#include "cocos/plugins/Plugins.h" #include "cocos/bindings/manual/jsb_classtype.h" #include "cocos/bindings/manual/jsb_global.h" #include "cocos/bindings/manual/jsb_module_register.h" @@ -56,6 +57,8 @@ Game::~Game() { int Game::init() { cc::pipeline::GlobalDSManager::setDescriptorSetLayout(); + // Mirrors BaseGame::init(): register native plugins before any script runs. + cc_load_all_plugins(); SimulatorApp::getInstance()->init(); std::call_once(_windowCreateFlag, [&]() { cc::ISystemWindowInfo info; diff --git a/native/tools/simulator/libsimulator/lib/protobuf-lite/config.h b/native/tools/simulator/libsimulator/lib/protobuf-lite/config.h index c1df8dd4d0..307355ebe8 100755 --- a/native/tools/simulator/libsimulator/lib/protobuf-lite/config.h +++ b/native/tools/simulator/libsimulator/lib/protobuf-lite/config.h @@ -30,6 +30,11 @@ /* protobuf config.h for MSVC. On other platforms, this is generated * automatically by autoheader / autoconf / configure. */ +/* VS 18 (MSVC >= 1950) removed the legacy / headers. + * Leave the HAVE_* flags undefined there so stubs/hash.h takes its built-in + * MISSING_HASH fallback (std::map / std::set based). */ +#if !(defined(_MSC_VER) && _MSC_VER >= 1950) + /* the location of */ #define HASH_MAP_H @@ -53,6 +58,8 @@ /* define if the compiler has hash_set */ #define HAVE_HASH_SET 1 +#endif // MSVC >= 1950 + /* define if you want to use zlib. See readme.txt for additional * requirements. */ // #define HAVE_ZLIB 1 diff --git a/scripts/build-adapter.js b/scripts/build-adapter.js index 1d0666d92e..7fcd9f765c 100644 --- a/scripts/build-adapter.js +++ b/scripts/build-adapter.js @@ -78,9 +78,15 @@ async function bundleRuntimeAdapter () { const platforms = getPlatformsFromPath(platformsPath); console.log(green(`\nBundling runtime platform adapters, including: ${platforms}`)); for (const platform of platforms) { + const engineEntry = normalizePath(ps.join(engineRoot, `platforms/runtime/platforms/${platform}/engine/index.js`)); + // Some platform dirs may be incomplete in a checkout (missing engine files); + // skip them instead of crashing the adapter build. + if (!fs.existsSync(engineEntry)) { + console.log(`skip platform: ${platform} (missing ${engineEntry})`); + continue; + } console.log(`handle platform: ${green(platform)}`); // bundle engine-adapter.js - const engineEntry = normalizePath(ps.join(engineRoot, `platforms/runtime/platforms/${platform}/engine/index.js`)); const engineOutput = normalizePath(ps.join(engineRoot, `bin/adapter/runtime/${platform}/engine-adapter.js`)); await bundle(engineEntry, engineOutput, true); } diff --git a/templates/cmake/common.cmake b/templates/cmake/common.cmake index f113836f31..f44849a4ba 100644 --- a/templates/cmake/common.cmake +++ b/templates/cmake/common.cmake @@ -60,14 +60,19 @@ endfunction() function(cc_gen_plugin_cmake_hook) - set(project_root_dir ${CC_PROJECT_DIR}/../../..) set(load_plugin_cmake ${CC_PROJECT_DIR}/Pre-AutoLoadPlulgins.cmake) message(STATUS "Try generating ${load_plugin_cmake}") file(REMOVE ${load_plugin_cmake}) - list(APPEND CC_PLUGIN_PATH - ${project_root_dir}/native - ${project_root_dir}/extensions - ) + # Scan roots default to the native-build project layout; callers that host + # the scan elsewhere (e.g. the Simulator, pointed at an arbitrary + # extensions tree) may pre-set CC_PLUGIN_PATH with their own roots. + if(NOT DEFINED CC_PLUGIN_PATH) + set(project_root_dir ${CC_PROJECT_DIR}/../../..) + list(APPEND CC_PLUGIN_PATH + ${project_root_dir}/native + ${project_root_dir}/extensions + ) + endif() set(plugin_args_info ${CMAKE_CURRENT_BINARY_DIR}/plugin_dirs.txt) file(WRITE ${plugin_args_info} "# directories for searching native plugins\n") foreach(dir ${CC_PLUGIN_PATH}) diff --git a/tests/ui/ui-mesh.test.ts b/tests/ui/ui-mesh.test.ts new file mode 100644 index 0000000000..0146d8c86c --- /dev/null +++ b/tests/ui/ui-mesh.test.ts @@ -0,0 +1,438 @@ +import { UIMesh, UIMeshData } from '../../cocos/2d/components/ui-mesh'; +import { UITransform } from '../../cocos/2d'; +import { UIOpacity } from '../../cocos/2d/components/ui-opacity'; +import { Node } from '../../cocos/scene-graph/node'; +import { Scene, director } from '../../exports/base'; +import { Batcher2D } from '../../cocos/2d/renderer/batcher-2d'; +import { vfmtPosUvColor4B, vfmtPosUvTwoColor4B } from '../../cocos/2d/renderer/vertex-format'; +import { Vec3 } from '../../cocos/core/math/vec3'; +import { captureErrorIDs } from '../utils/log-capture'; + +// Mirrors sprite.test.ts: a headless batcher so UIMesh can create its shared +// StaticVBAccessor and allocate chunks from it. +// @ts-expect-error +director.root!._batcher = new Batcher2D(director.root!); +const scene = new Scene('uimesh-test'); +director.runSceneImmediate(scene); + +const ACCESSOR_VERTEX_COUNT = 32767; + +function createUIMesh (parent: Node = scene): { mesh: UIMesh, anyMesh: any, node: Node } { + const node = new Node('mesh'); + node.addComponent(UITransform); + parent.addChild(node); + const mesh = node.addComponent(UIMesh); + return { mesh, anyMesh: mesh as any, node }; +} + +function makeMeshData (vc: number, stride = 24): UIMeshData { + const quadCount = Math.floor(vc / 4); + const ic = quadCount * 6; + const vertexData = new Uint8Array(vc * stride); + const indices = new Uint16Array(ic); + for (let q = 0; q < quadCount; ++q) { + const v = q * 4; + const o = q * 6; + indices[o] = v; indices[o + 1] = v + 1; indices[o + 2] = v + 2; + indices[o + 3] = v + 2; indices[o + 4] = v + 1; indices[o + 5] = v + 3; + } + return { + vertexCount: vc, + vertexStride: stride, + vertexData, + indexCount: ic, + indexData: new Uint8Array(indices.buffer), + segments: [{ indexOffset: 0, indexCount: ic, texture: null, material: null }], + }; +} + +describe('UIMesh: accessor capacity', () => { + test('30000 vertices render — the 10% reserve is clamped to the accessor cap', () => { + const { mesh, anyMesh } = createUIMesh(); + const data = makeMeshData(30000); // fits, but ceil(30000 * 1.1) > 32767 + mesh.setMeshData(data); + expect(anyMesh._meshData).toBe(data); + expect(anyMesh._prepareBuffers()).not.toBeNull(); + const rd = anyMesh._renderData; + // Actual counts are tracked; the reserve lives in the chunk. + expect(rd.vertexCount).toBe(30000); + expect(rd.indexCount).toBe(data.indexCount); + expect(rd.chunk).toBeTruthy(); + expect(rd.chunk.vb.byteLength).toBe(ACCESSOR_VERTEX_COUNT * 24); + }); + + test('32767 vertices (exact accessor cap) render', () => { + const { mesh, anyMesh } = createUIMesh(); + mesh.setMeshData(makeMeshData(32767)); + expect(anyMesh._prepareBuffers()).not.toBeNull(); + const rd = anyMesh._renderData; + expect(rd.vertexCount).toBe(32767); + expect(rd.chunk.vb.byteLength).toBe(ACCESSOR_VERTEX_COUNT * 24); + }); + + test('data beyond the accessor cap is rejected with an error', () => { + const { mesh, anyMesh } = createUIMesh(); + const watcher = captureErrorIDs(); + mesh.setMeshData(makeMeshData(32768)); + expect(watcher.captured).toHaveLength(1); + expect(watcher.captured[0]).toEqual([9016, 32768, 49152, 32767, 131068]); + watcher.clear(); + expect(anyMesh._meshData).toBeNull(); // rejected frame stores nothing + }); + + test('growth within the reserve does not reallocate the chunk', () => { + const { mesh, anyMesh } = createUIMesh(); + mesh.setMeshData(makeMeshData(100)); + expect(anyMesh._prepareBuffers()).not.toBeNull(); + const chunk = anyMesh._renderData.chunk; + mesh.setMeshData(makeMeshData(105)); // within the ~10% head room + expect(anyMesh._prepareBuffers()).not.toBeNull(); + expect(anyMesh._renderData.chunk).toBe(chunk); + expect(anyMesh._renderData.vertexCount).toBe(105); + }); +}); + +describe('UIMesh: setMeshData boundary validation', () => { + let mesh: UIMesh; + let anyMesh: any; + let watcher: ReturnType; + + beforeEach(() => { + ({ mesh, anyMesh } = createUIMesh()); + watcher = captureErrorIDs(); + }); + + // The watcher must be empty by test end (log-capture afterEach enforces it): + // every test asserts its single errorID call and clears it. Entries are the + // raw errorID arguments — [id, ...params]; the texts live in DebugInfos.json. + afterEach(() => { + watcher.clear(); + }); + + test('rejects unsupported vertex stride', () => { + mesh.setMeshData(makeMeshData(8, 32)); + expect(watcher.captured).toHaveLength(1); + expect(watcher.captured[0]).toEqual([9010, 32, 24, 28]); + expect(anyMesh._meshData).toBeNull(); + }); + + test('rejects vertexData shorter than vertexCount * stride', () => { + const data = makeMeshData(8); + data.vertexData = data.vertexData.slice(0, data.vertexData.byteLength - 1); + mesh.setMeshData(data); + expect(watcher.captured).toHaveLength(1); + expect(watcher.captured[0]).toEqual([9012, 191, 8, 24]); + expect(anyMesh._meshData).toBeNull(); + }); + + test('rejects indexData shorter than indexCount * 2', () => { + const data = makeMeshData(8); + data.indexData = data.indexData.slice(0, data.indexData.byteLength - 2); + mesh.setMeshData(data); + expect(watcher.captured).toHaveLength(1); + expect(watcher.captured[0]).toEqual([9013, 22, 0, 12, 24]); + expect(anyMesh._meshData).toBeNull(); + }); + + test('rejects indices out of vertex range', () => { + const data = makeMeshData(8); + const indices = new Uint16Array(data.indexData.buffer, data.indexData.byteOffset, data.indexCount); + indices[0] = data.vertexCount; // one past the last vertex + mesh.setMeshData(data); + expect(watcher.captured).toHaveLength(1); + expect(watcher.captured[0]).toEqual([9014, 0, 8, 8]); + expect(anyMesh._meshData).toBeNull(); + }); + + test('rejects segment ranges beyond indexCount', () => { + const data = makeMeshData(8); + data.segments = [{ indexOffset: 0, indexCount: data.indexCount + 1, texture: null, material: null }]; + mesh.setMeshData(data); + expect(watcher.captured).toHaveLength(1); + expect(watcher.captured[0]).toEqual([9015, 0, 0, 13, 12]); + expect(anyMesh._meshData).toBeNull(); + }); + + test('a rejected frame keeps the last accepted mesh', () => { + const good = makeMeshData(8); + mesh.setMeshData(good); + mesh.setMeshData(makeMeshData(32768)); // over cap, rejected + expect(watcher.captured).toHaveLength(1); + expect(watcher.captured[0]).toEqual([9016, 32768, 49152, 32767, 131068]); + expect(anyMesh._meshData).toBe(good); + }); +}); + +describe('UIMesh: accessor lifetime follows the batcher', () => { + test('a rebuilt root/batcher never reuses a destroyed accessor (single- and two-color)', () => { + const UIMESH_KEY = Number.parseInt('UIMESH', 36); + const UIMESH_TINT_KEY = Number.parseInt('UIMESHTINT', 36); + + // First root: a UIMesh creates its accessors and registers them with + // the current batcher. + const first = createUIMesh(); + first.mesh.setMeshData(makeMeshData(8)); + expect(first.anyMesh._prepareBuffers()).not.toBeNull(); + const oldAccessor = first.anyMesh._renderData.accessor; + const oldMap: Map = (director.root!.batcher2D as any)._bufferAccessors; + expect(oldMap.get(UIMESH_KEY)).toBe(oldAccessor); // registered with its batcher + + // Root.destroy(): the batcher destroys every accessor it owns, is + // dropped, and a rebuilt root creates a fresh batcher with an empty map + // — all within the same JS context. + const root: any = director.root!; + const oldBatcher: Batcher2D = root.batcher2D; + oldBatcher.destroy(); + expect(oldMap.size).toBe(0); // accessors released with the batcher + expect((oldAccessor as any)._buffers.length).toBe(0); // buffers gone + root._batcher = new Batcher2D(root); + + // UIMesh components under the new root must resolve fresh accessors + // from the new batcher. A batcher-keyed cache that forgot to invalidate + // would hand back the destroyed accessor and skip registration, + // breaking upload/reset. + const second = createUIMesh(); + second.mesh.setMeshData(makeMeshData(8)); + expect(second.anyMesh._prepareBuffers()).not.toBeNull(); + const newAccessor = second.anyMesh._renderData.accessor; + expect(newAccessor).not.toBe(oldAccessor); + expect((newAccessor as any)._buffers.length).toBeGreaterThan(0); + + const newMap: Map = (director.root!.batcher2D as any)._bufferAccessors; + expect(newMap.get(UIMESH_KEY)).toBe(newAccessor); // registered with the new batcher + + // Two-color branch: same guarantee for the tint accessor. + const tinted = createUIMesh(); + tinted.mesh.setMeshData(makeMeshData(8, 28)); + expect(tinted.anyMesh._prepareBuffers()).not.toBeNull(); + const newTintAccessor = tinted.anyMesh._renderData.accessor; + expect(newTintAccessor).not.toBe(oldAccessor); + expect(newMap.get(UIMESH_TINT_KEY)).toBe(newTintAccessor); + + // The accessors hold copies of the vertex formats: destroying them with + // the old batcher must not empty the shared module-level constants. + expect(vfmtPosUvColor4B).toHaveLength(3); + expect(vfmtPosUvTwoColor4B).toHaveLength(4); + }); +}); + +// A drawable segment: a texture is what makes _prepareNativeDrawInfos create a +// draw info (segments without texture are skipped). Only getGFXTexture / +// getGFXSampler are called headless. +const fakeTexture = (): any => ({ getGFXTexture: () => ({}), getGFXSampler: () => ({}) }); + +function makeDrawnData (vc: number): UIMeshData { + const data = makeMeshData(vc); + data.segments = [{ indexOffset: 0, indexCount: data.indexCount, texture: fakeTexture(), material: {} as any }]; + return data; +} + +describe('UIMesh: per-frame index submission (native cross-frame)', () => { + // The native batcher resets every mesh buffer's index tail after upload + // (indexOffset = 0, synchronized through shared memory) while only dirty + // renderers re-prepare. jest runs with JSB = false, so these tests drive + // the JSB pump's two submit paths directly: appendIndexBuffer (static + // frame) and _prepareNativeDrawInfos (dirty frame) -- each runs exactly + // once per frame. The helper below performs the post-upload reset. + const nextFrame = (buf: any): void => { + buf.indexOffset = 0; // the post-upload index-tail reset + }; + + test('a paused mesh keeps drawing its own triangles while a sibling updates', () => { + const a = createUIMesh(); + const b = createUIMesh(); + a.mesh.setMeshData(makeDrawnData(4)); // ic = 6 + b.mesh.setMeshData(makeDrawnData(4)); + + // Frame 1: both dirty -> both run the native draw-info refresh. + a.anyMesh._prepareNativeDrawInfos(); + b.anyMesh._prepareNativeDrawInfos(); + const buf = a.anyMesh._renderData.getMeshBuffer(); + expect(b.anyMesh._renderData.getMeshBuffer()).toBe(buf); // one shared buffer + const offsetA = a.anyMesh._renderData.chunk.vertexOffset; + const offsetB = b.anyMesh._renderData.chunk.vertexOffset; + expect(offsetB).toBeGreaterThan(offsetA); + const quadOf = (o: number): Uint16Array => new Uint16Array([o, o + 1, o + 2, o + 2, o + 1, o + 3]); + const startA = a.anyMesh._drawInfoList[0]._indexOffset; + const startB = b.anyMesh._drawInfoList[0]._indexOffset; + expect(startB - startA).toBe(6); // B appended right after A + expect(buf.iData.slice(startA, startA + 6)).toEqual(quadOf(offsetA)); + expect(buf.iData.slice(startB, startB + 6)).toEqual(quadOf(offsetB)); + + // Frame 2: A paused (no setMeshData), B advancing. + nextFrame(buf); + b.mesh.setMeshData(makeDrawnData(4)); // B's producer, update phase + a.anyMesh.appendIndexBuffer(); // A's pump: static, index-only resubmit + b.anyMesh._prepareNativeDrawInfos(); // B's pump: dirty, full refresh + + // A's cached draw info still points at a range holding A's OWN indices. + // Without the per-frame resubmit, B would append at the reset offset 0 + // and A (start 0, never refreshed) would draw B's vertices. + expect(a.anyMesh._drawInfoList[0]._indexOffset).toBe(0); + expect(b.anyMesh._drawInfoList[0]._indexOffset).toBe(6); + expect(buf.iData.slice(0, 6)).toEqual(quadOf(offsetA)); + expect(buf.iData.slice(6, 12)).toEqual(quadOf(offsetB)); + expect(buf.indexOffset).toBe(12); // one append per mesh — the pump is the single driver + }); + + test('each frame appends once; re-feeding the same object resubmits', () => { + const { mesh, anyMesh } = createUIMesh(); + const data = makeMeshData(4); + mesh.setMeshData(data); + expect(anyMesh._prepareBuffers()).not.toBeNull(); // establishes the chunk + const buf = anyMesh._renderData.getMeshBuffer(); + const offset = anyMesh._renderData.chunk.vertexOffset; + const quadOf = (o: number): Uint16Array => new Uint16Array([o, o + 1, o + 2, o + 2, o + 1, o + 3]); + + nextFrame(buf); + anyMesh.appendIndexBuffer(); // the pump's static-frame path + expect(buf.indexOffset).toBe(6); + expect(buf.iData.slice(0, 6)).toEqual(quadOf(offset)); + + nextFrame(buf); + mesh.setMeshData(data); // SAME object, mutated in place by the producer + anyMesh.appendIndexBuffer(); + expect(buf.indexOffset).toBe(6); // setMeshData latched a refresh; fresh append at the reset tail + expect(buf.iData.slice(0, 6)).toEqual(quadOf(offset)); + }); +}); + +describe('UIMesh: batched bake applies the full world matrix', () => { + const writePositions = (data: UIMeshData, locals: Vec3[]): void => { + const floats = new Float32Array(data.vertexData.buffer, data.vertexData.byteOffset, data.vertexData.byteLength >> 2); + locals.forEach((v, i) => { + floats[i * 6] = v.x; floats[i * 6 + 1] = v.y; floats[i * 6 + 2] = v.z; + }); + }; + const chunkPosition = (anyMesh: any, i: number): Vec3 => { + const vb = anyMesh._renderData.chunk.vb; // stride 24 = 6 floats + return new Vec3(vb[i * 6], vb[i * 6 + 1], vb[i * 6 + 2]); + }; + + test('a parent Z translation reaches the batched vertices: local (1,2,3) + z+10 -> (1,2,13)', () => { + const parent = new Node('parent'); + parent.addComponent(UITransform); + scene.addChild(parent); + parent.setPosition(0, 0, 10); + const { mesh, anyMesh } = createUIMesh(parent); // node itself stays identity + + const data = makeMeshData(4); + writePositions(data, [new Vec3(1, 2, 3), new Vec3(-1, 2, 3), new Vec3(1, -2, -3), new Vec3(-1, -2, -3)]); + anyMesh._enableBatch = true; // direct: the public setter also recompiles materials + mesh.setMeshData(data); + expect(anyMesh._prepareBuffers()).not.toBeNull(); + + // The old 2D-only bake kept z at 3; the GPU path (pos = cc_matWorld * pos) + // produces 13, and so must the baked chunk. + const got = chunkPosition(anyMesh, 0); + expect(got.x).toBeCloseTo(1, 6); + expect(got.y).toBeCloseTo(2, 6); + expect(got.z).toBeCloseTo(13, 6); + }); + + test('batched chunk equals the full world matrix applied to the unbatched chunk (toggle consistency)', () => { + const parent = new Node('parent'); + parent.addComponent(UITransform); + scene.addChild(parent); + parent.setPosition(1, 2, 10); + parent.setRotationFromEuler(30, 0, 0); // X-axis rotation + const { mesh, anyMesh, node } = createUIMesh(parent); + node.setPosition(0.5, -0.25, 2); + node.setRotationFromEuler(0, 45, 0); // Y-axis rotation + + const locals = [new Vec3(1, 2, 3), new Vec3(-4, 5, -6), new Vec3(7, -8, 9), new Vec3(-10, -11, -12)]; + const data = makeMeshData(4); + writePositions(data, locals); + + // Unbatched: the chunk stays node-local (the GPU applies cc_matWorld). + anyMesh._enableBatch = false; + mesh.setMeshData(data); + expect(anyMesh._prepareBuffers()).not.toBeNull(); + const localChunk = [0, 1, 2, 3].map((i) => chunkPosition(anyMesh, i)); + + // Batched: the chunk holds the world matrix baked on the CPU. What the + // GPU would compute for the unbatched data and what the batched data + // carries must agree component by component, z and X/Y rotation included. + anyMesh._enableBatch = true; + expect(anyMesh._prepareBuffers()).not.toBeNull(); + const wm = node.worldMatrix; + for (let i = 0; i < 4; i++) { + const expected = new Vec3(); + Vec3.transformMat4(expected, localChunk[i], wm); + const got = chunkPosition(anyMesh, i); + expect(got.x).toBeCloseTo(expected.x, 5); + expect(got.y).toBeCloseTo(expected.y, 5); + expect(got.z).toBeCloseTo(expected.z, 5); + } + + // The JSB staleness poll must track the full matrix the bake consumes: + // a paused mesh that moves in Z or rotates in X/Y still has to re-bake. + // The capture after a batched prepare is exactly what _onBeforeDraw + // compares against on the next frame. + expect(Math.abs(wm.m02)).toBeGreaterThan(0.5); // the rotations are live + expect(anyMesh._pollWorldMatrix.strictEquals(wm)).toBe(true); + }); +}); + +describe('UIMesh: cascaded opacity includes ancestor renderer color.a', () => { + const makeParentWithRenderer = (alpha: number): { parent: Node, parentMesh: any } => { + const parent = new Node('parent'); + parent.addComponent(UITransform); + scene.addChild(parent); + const parentMesh = parent.addComponent(UIMesh) as any; + parentMesh._color.a = alpha; // direct write: the setter drags color-update machinery in + return { parent, parentMesh }; + }; + + test('a parent renderer at color.a 128 fades the child to ~0.502', () => { + const { parent } = makeParentWithRenderer(128); + const { anyMesh } = createUIMesh(parent); + // Own alpha 255 x parent level (UIOpacity 1 x renderer 128/255). The old + // computation stopped at localOpacity and returned 1 here. + expect(anyMesh._computeCascadedOpacity()).toBeCloseTo(128 / 255, 6); + }); + + test('UIOpacity localOpacity and renderer alpha accumulate at every ancestor level', () => { + const grand = new Node('grand'); + grand.addComponent(UITransform); + scene.addChild(grand); + grand.addComponent(UIOpacity).opacity = 204; // localOpacity 0.8 + const parent = new Node('parent'); + parent.addComponent(UITransform); + grand.addChild(parent); + const parentMesh = parent.addComponent(UIMesh) as any; + parentMesh._color.a = 128; + parent.addComponent(UIOpacity).opacity = 128; // localOpacity 128/255 + const { anyMesh } = createUIMesh(parent); + + expect(anyMesh._computeCascadedOpacity()).toBeCloseTo((204 / 255) * (128 / 255) * (128 / 255), 6); + }); + + test('a paused mesh picks up ancestor color.a changes (the JSB poll input)', () => { + const { parent, parentMesh } = makeParentWithRenderer(128); + const { mesh, anyMesh } = createUIMesh(parent); + const data = makeMeshData(4); + // vfmtPosUvColor4B: pos 12B + uv 8B puts the color attribute at bytes + // 20..23 of the 24-byte vertex — alpha lives at 23. + for (let i = 0; i < 4; i++) data.vertexData[i * 24 + 23] = 255; // opaque alpha bytes + mesh.setMeshData(data); + expect(anyMesh._prepareBuffers()).not.toBeNull(); + expect(anyMesh._pollOpacity).toBeCloseTo(128 / 255, 6); // captured by the last active frame + + // The ancestor fades while this mesh is paused: no engine event marks a + // middleware renderer dirty -- the update() poll compares exactly this + // value and re-marks on drift. + parentMesh._color.a = 64; + expect(anyMesh._computeCascadedOpacity()).not.toBe(anyMesh._pollOpacity); + + // The refresh the poll triggers re-folds the new opacity into the + // copied vertices' alpha bytes. + expect(anyMesh._prepareBuffers()).not.toBeNull(); + expect(anyMesh._pollOpacity).toBeCloseTo(64 / 255, 6); + const vb = anyMesh._renderData.chunk.vb; + const bytes = new Uint8Array(vb.buffer, vb.byteOffset, 4 * 24); + for (let i = 0; i < 4; i++) { + expect(bytes[i * 24 + 23]).toBe(64); // 255 * (64 / 255) + } + }); +});