add a function to enable texel offset for tilemap (#18209)

* add a function to enable texel offset for tilemap
cocos · Jan 21, 2025 · f5f9a5a · f5f9a5a
1 parent f965829
commit f5f9a5a
Show file tree

Hide file tree

Showing 2 changed files with 36 additions and 5 deletions.
diff --git a/cocos/tiledmap/tiled-map.ts b/cocos/tiledmap/tiled-map.ts
@@ -33,7 +33,7 @@ import { TiledLayer } from './tiled-layer';
 import { TiledObjectGroup } from './tiled-object-group';
 import { TiledMapAsset } from './tiled-map-asset';
 import { Sprite } from '../2d/components/sprite';
-import { fillTextureGrids } from './tiled-utils';
+import { fillTextureGrids, enableTexelOffsetUtils } from './tiled-utils';
 import { Size, Vec2, logID, Color, sys, warnID } from '../core';
 import { SpriteFrame } from '../2d/assets';
 import { NodeEventType } from '../scene-graph/node-event';
@@ -303,6 +303,22 @@ export class TiledMap extends Component {
         return this._tileProperties.get(gid);
     }
 
+    /**
+     * @en Enables or disables texel offset correction to fix rendering issues like grid edge artifacts.
+     * This function adjusts the texture coordinates of each grid in the tilemap by applying
+     * a 0.5-pixel offset, ensuring that grid edges do not show black lines or artifacts caused by
+     * texture sampling inaccuracies. This is especially useful for tile-based rendering systems.
+     * @zh 启用或禁用像素偏移修正，用于修复网格边缘的渲染问题（如黑线）。此函数通过对每个 tilemap 网格的纹理坐标应用 0.5 像素
+     * 的偏移来调整，确保网格边缘不会出现因纹理采样不准确导致的黑线或其他伪影问题。对基于图块的渲染系统特别有用。
+     *
+     * @param enable
+     * @en Whether to enable (true) or disable (false) the texel offset correction.
+     * @zh 是否启用 (true) 或禁用 (false) 像素偏移修正。
+     */
+    enableTexelOffset (enable: boolean): void {
+        enableTexelOffsetUtils(enable);
+    }
+
     __preload (): void {
         if (!this._tmxFile) {
             return;

diff --git a/cocos/tiledmap/tiled-utils.ts b/cocos/tiledmap/tiled-utils.ts
@@ -27,6 +27,12 @@ import { Texture2D } from '../asset/assets';
 import { Rect } from '../core';
 import { GID, TiledGrid, TiledTextureGrids, TMXTilesetInfo } from './tiled-types';
 
+let _enableTexelOffset = false;
+
+export function enableTexelOffsetUtils (enable: boolean): void {
+    _enableTexelOffset = enable;
+}
+
 export function fillTextureGrids (tileset: TMXTilesetInfo, texGrids: TiledTextureGrids, spFrame?: SpriteFrame): void {
     const spf: SpriteFrame = spFrame || tileset.sourceImage!;
     const tex: Texture2D = spf.texture as Texture2D;
@@ -100,10 +106,19 @@ export function fillTextureGrids (tileset: TMXTilesetInfo, texGrids: TiledTextur
                 grid._name = spFrame.name;
                 const lm = spFrame.unbiasUV[0];
                 const bm = spFrame.rotated ? spFrame.unbiasUV[1] : spFrame.unbiasUV[5];
-                grid.l = lm + (grid.x) / texWidth;
-                grid.t = bm + (grid.y) / texHeight;
-                grid.r = lm + (grid.x + grid.width) / texWidth;
-                grid.b = bm + (grid.y + grid.height) / texHeight;
+
+                if (_enableTexelOffset) {
+                    grid.l = lm + (grid.x + 0.5) / texWidth;
+                    grid.t = bm + (grid.y + 0.5) / texHeight;
+                    grid.r = lm + (grid.x + grid.width - 0.5) / texWidth;
+                    grid.b = bm + (grid.y + grid.height - 0.5) / texHeight;
+                } else {
+                    grid.l = lm + (grid.x) / texWidth;
+                    grid.t = bm + (grid.y) / texHeight;
+                    grid.r = lm + (grid.x + grid.width) / texWidth;
+                    grid.b = bm + (grid.y + grid.height) / texHeight;
+                }
+
                 grid._rect = new Rect(grid.x, grid.y, grid.width, grid.height);
             } else {
                 grid.l = grid.x / texWidth;