Supports configuring a larger BATCHER2D_MEM_INCREMENT

cocos/2d/renderer/mesh-buffer.ts

@@ -23,7 +23,7 @@
 */
 
 import { JSB } from 'internal:constants';
-import { Device, BufferUsageBit, MemoryUsageBit, Attribute, Buffer, BufferInfo, InputAssembler, InputAssemblerInfo } from '../../gfx';
+import { Device, BufferUsageBit, MemoryUsageBit, Attribute, Buffer, BufferInfo, InputAssembler, InputAssemblerInfo, Feature, API } from '../../gfx';
 import { getAttributeStride } from './vertex-format';
 import { sys, getError, warnID, assertIsTrue } from '../../core';
 import { NativeUIMeshBuffer } from './native-2d';
@@ -251,7 +251,12 @@
 
         this.floatsPerVertex = getAttributeStride(attrs) >> 2;
 
-        assertIsTrue(this._initVDataCount / this._floatsPerVertex < 65536, getError(9005));
+        var vDataCountLimit = 65536; // 2^16 - 1
+        const glApi = device.gfxAPI;
+        if (glApi === API.WEBGPU || glApi === API.WEBGL2 || glApi === API.WEBGL && device.hasFeature(Feature.ELEMENT_INDEX_UINT)) {
+            vDataCountLimit = 4294967295; // 2^32 - 1
+        }
+        assertIsTrue(this._initVDataCount / this._floatsPerVertex < vDataCountLimit, getError(9005));
 
         if (!this.vData || !this.iData) {
             this.vData = new Float32Array(this._initVDataCount);

cocos/core/platform/macro.ts

@@ -910,7 +910,7 @@
     ORIENTATION_PORTRAIT_UPSIDE_DOWN: number;
 
     /**
      * @en Oriented horizontally. Users cannot directly listen to this value; they need to listen for ORIENTATION_LANDSCAPE_LEFT or ORIENTATION_LANDSCAPE_RIGHT.
      * @zh 横屏朝向, 外部不能直接监听该值，需要监听 ORIENTATION_LANDSCAPE_LEFT 或 ORIENTATION_LANDSCAPE_RIGHT
      */
     ORIENTATION_LANDSCAPE: number;
@@ -1006,7 +1006,7 @@
 
     /**
      * @en
      * Used to set float output render target, more accurate multiple light sources, fog, and translucent effects, custom pipeline only, the default value is false.
      * @zh
      * 用于开启浮点格式的RT输出, 更精确的多光源、雾化和半透明效果, 仅用于自定义管线, 默认值为 false。
      * @default false
@@ -1066,17 +1066,25 @@
     ENABLE_WEBGL_HIGHP_STRUCT_VALUES: boolean;
 
     /**
-     * @zh Batcher2D 中内存增量的大小（KB）
-     * 这个值决定了当场景中存在的 2d 渲染组件的顶点数量超过当前 batcher2D 中可容纳的顶点数量时，内存扩充的增加量
-     * 这个值越大，共用同一个 meshBuffer 的 2d 渲染组件数量会更多，但每次扩充所占用的内存也会更大
-     * 默认值在标准格式（[[VertexFormat.vfmtPosUvColor]]）下可容纳 4096 个顶点（4096*9*4/1024），你可以增加容量来提升每个批次可容纳的元素数量
-     * @en The MeshBuffer chunk size in Batcher2D (KB)
-     * This value determines the increase in memory expansion,
-     * when the number of vertices of 2d rendering components present in the scene exceeds the number of vertices,
-     * that can be accommodated in the current batcher2D.
-     * The larger this value is, the more 2d rendering components will share the same meshBuffer, but the more memory will be used for each expansion
-     * The default size can contain 4096 standard vertex ([[VertexFormat.vfmtPosUvColor]]) in one buffer,
-     * you can user larger buffer size to increase the elements count per 2d draw batch.
+     * @zh Batcher2D 中每个渲染批次的内存增量（KB）
+     * 增大此值能使参与渲染合批的 2d 渲染组件数量增加，但是每次增加渲染批次的内存增量也会变大。
+     * 这个值决定每个 2D 渲染批次的顶点数量，计算公式为 vCount = Math.floor(macro.BATCHER2D_MEM_INCREMENT * 1024 / 9 * 4);
+     * WebGL2 & WebGPU 等渲染后端的最大顶点数量通常是 2^32 - 1，即 4294967295。
+     * WebGL1 渲染后端的最大顶点数量通常是 2^16 - 1，即 65535。引擎使用拓展 OES_element_index_uint 突破了这个限制，最大顶点数量也可达到 2^32 - 1。
+     * 所以 macro.BATCHER2D_MEM_INCREMENT 的理论最大值为 150994943，但是因为所运行平台的 js 引擎对 Float32Array|Uint16Array 的最大长度有限制，实际最大值往往会小于 2^32 - 1。
+     * 建议最大值不超过 1048576 kb (1GB)，否则会因为 js 引擎的限制而导致 buffer 创建失败。
+     * @en Memory increment (KB) for each rendering batch in Batcher2D
+     * Increasing this value can increase the number of 2D rendering components involved in rendering batching, but the memory increment for each additional rendering batch will also become larger.
+     * This value determines the number of vertices in each 2D rendering batch, calculated as vCount = Math.floor(macro.BATCHER2D_MEM_INCREMENT * 1024 / 9 * 4);
+     * The maximum number of vertices for rendering backends such as WebGL2 & WebGPU is usually 2^32 - 1, which is 4294967295.
+     * The maximum number of vertices for the WebGL1 rendering backend is usually 2^16 - 1, which is 65535. The engine uses the extension OES_element_index_uint to break this limit, and the maximum number of vertices can also reach 2^32 - 1.
+     * Therefore, the theoretical maximum value of macro.BATCHER2D_MEM_INCREMENT is 150994943. However, due to the limitations of the JS engine on the maximum length of Float32Array|Uint16Array on the running platform, the actual maximum value is often less than 2^32 - 1.
+     * It is recommended that the maximum value does not exceed 1048576 kb (1GB); otherwise, buffer creation will fail due to JS engine limitations.
+     * @example
+     * ```typescript
+     * import { macro } from 'cc';
+     * macro.BATCHER2D_MEM_INCREMENT = 4096; //4096 KB
+     * ```
      * @default 144 KB
      */
     BATCHER2D_MEM_INCREMENT: number;