gfx: refactor binding mappings

[YunHsiao]

Re: cocos-creator/3d-tasks#

cocos/engine-native#4195

Changelog:

• refactor binding mappings to adapt more shader input data types
• fix issue caused by PyYAML 6.0 load() function requires Loader argument yaml/pyyaml#576

[github-actions]

Interface Check Report

! WARNING this pull request has changed these public interfaces:

@@ -11710,11 +11710,12 @@
             GLES2 = 1,
             GLES3 = 2,
             METAL = 3,
             VULKAN = 4,
-            WEBGL = 5,
-            WEBGL2 = 6,
-            WEBGPU = 7
+            NVN = 5,
+            WEBGL = 6,
+            WEBGL2 = 7,
+            WEBGPU = 8
         }
         export enum SurfaceTransform {
             IDENTITY = 0,
             ROTATE_90 = 1,
@@ -12309,13 +12310,33 @@
             w: number;
             constructor(x?: number, y?: number, z?: number, w?: number);
             copy(info: Readonly<Color>): this;
         }
+        /**
+         * For non-vulkan backends, to maintain compatibility and maximize
+         * descriptor cache-locality, descriptor-set-based binding numbers need
+         * to be mapped to backend-specific bindings based on maximum limit
+         * of available descriptor slots in each set.
+         *
+         * The GFX layer assumes the binding numbers for each descriptor type inside each set
+         * are guaranteed to be consecutive, so the mapping procedure is reduced
+         * to a simple shifting operation. This data structure specifies the
+         * capacity for each descriptor type in each set.
+         *
+         * The `setIndices` field defines the binding ordering between different sets.
+         * The last set index is treated as the 'flexible set', whose capacity is dynamically
+         * assigned based on the total available descriptor slots on the runtime device.
+         */
         export class BindingMappingInfo {
-            bufferOffsets: number[];
-            samplerOffsets: number[];
-            flexibleSet: number;
-            constructor(bufferOffsets?: number[], samplerOffsets?: number[], flexibleSet?: number);
+            maxBlockCounts: number[];
+            maxSamplerTextureCounts: number[];
+            maxSamplerCounts: number[];
+            maxTextureCounts: number[];
+            maxBufferCounts: number[];
+            maxImageCounts: number[];
+            maxSubpassInputCounts: number[];
+            setIndices: number[];
+            constructor(maxBlockCounts?: number[], maxSamplerTextureCounts?: number[], maxSamplerCounts?: number[], maxTextureCounts?: number[], maxBufferCounts?: number[], maxImageCounts?: number[], maxSubpassInputCounts?: number[], setIndices?: number[]);
             copy(info: Readonly<BindingMappingInfo>): this;
         }
         export class SwapchainInfo {
             windowHandle: HTMLCanvasElement;
@@ -34919,8 +34940,9 @@
         get extensions(): __private.cocos_core_gfx_webgl_webgl_define_IWebGLExtensions;
         get stateCache(): __private.cocos_core_gfx_webgl_webgl_state_cache_WebGLStateCache;
         get nullTex2D(): __private.cocos_core_gfx_webgl_webgl_texture_WebGLTexture;
         get nullTexCube(): __private.cocos_core_gfx_webgl_webgl_texture_WebGLTexture;
+        get bindingMappings(): __private.cocos_core_gfx_webgl_webgl_gpu_objects_IWebGLBindingMapping;
         initialize(info: gfx.DeviceInfo): boolean;
         destroy(): void;
         flushCommands(cmdBuffs: gfx.CommandBuffer[]): void;
         acquire(swapchains: gfx.Swapchain[]): void;
@@ -34950,8 +34972,9 @@
         get extensions(): __private.cocos_core_gfx_webgl2_webgl2_define_IWebGL2Extensions;
         get stateCache(): __private.cocos_core_gfx_webgl2_webgl2_state_cache_WebGL2StateCache;
         get nullTex2D(): __private.cocos_core_gfx_webgl2_webgl2_texture_WebGL2Texture;
         get nullTexCube(): __private.cocos_core_gfx_webgl2_webgl2_texture_WebGL2Texture;
+        get bindingMappings(): __private.cocos_core_gfx_webgl2_webgl2_gpu_objects_IWebGL2BindingMapping;
         initialize(info: gfx.DeviceInfo): boolean;
         destroy(): void;
         flushCommands(cmdBuffs: gfx.CommandBuffer[]): void;
         acquire(swapchains: gfx.Swapchain[]): void;
@@ -50026,8 +50049,13 @@
             destroy(): void;
             resize(width: number, height: number): void;
             protected initAsSwapchainTexture(info: gfx.ISwapchainTextureInfo): void;
         }
+        export interface cocos_core_gfx_webgl_webgl_gpu_objects_IWebGLBindingMapping {
+            blockOffsets: number[];
+            samplerTextureOffsets: number[];
+            flexibleSet: number;
+        }
         export interface cocos_core_gfx_webgl2_webgl2_define_IWebGL2Extensions {
             EXT_texture_filter_anisotropic: EXT_texture_filter_anisotropic | null;
             EXT_color_buffer_half_float: EXT_color_buffer_half_float | null;
             EXT_color_buffer_float: EXT_color_buffer_float | null;
@@ -50104,8 +50132,13 @@
             destroy(): void;
             resize(width: number, height: number): void;
             protected initAsSwapchainTexture(info: gfx.ISwapchainTextureInfo): void;
         }
+        export interface cocos_core_gfx_webgl2_webgl2_gpu_objects_IWebGL2BindingMapping {
+            blockOffsets: number[];
+            samplerTextureOffsets: number[];
+            flexibleSet: number;
+        }
         /**
          * @en Test line and line
          * @zh 测试线段与线段是否相交
          */

[pandamicro]

16bit count should be 32768

[YunHsiao]

This is synced from native changes @stanleyljl

[pandamicro]

Looks like a lot more data, have memory impact ?

[pandamicro]

And I don't understand why maxXXXCounts are arrays...

[YunHsiao]

The limits are given per descriptor set, thus the array structure.
The arrays are very small by nature, 4 elements at most according to vk spec. For our purposes this is fixed as length-3 arrays, corresponding to the 3 descriptor sets (global, material & local).

This interface is transparent to the upper layer most of the time, and the semantics should be pretty straightforward.
The complexities are all encapsulated inside the actual backends.

[pandamicro]

@cocos-robot run test cases