Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(render): uvRectFromPixels, the one pixel-rect to UV conversion, and docs for y-up UV space

yhhc8da7092edbb
diff --git a/docs/astro/src/content/docs/graphics/sprites.mdx b/docs/astro/src/content/docs/graphics/sprites.mdx
index cf101bb2f..8a1d248fc 100644
--- a/docs/astro/src/content/docs/graphics/sprites.mdx
+++ b/docs/astro/src/content/docs/graphics/sprites.mdx
@@ -387,6 +387,12 @@ so a sprite at z = -400 is grabbable where it is drawn.
the cell's normalized rectangle — or pack separate textures onto one canvas at run time with
[`TextureAtlas`](/docs/graphics/drawing/#packing-textures-onto-one-canvas-textureatlas). (For frame-by-frame animation, drive these from the
[Animator](/docs/animation/overview/) instead of by hand.)
+- **UV space is y-up**: `v = 0` is the picture's *bottom* row and `v = 1` its top, the
+ opposite of image-editor pixel coordinates. A cell measured in pixels from the top-left
+ converts with `uvRectFromPixels({ x, y, width, height }, textureWidth, textureHeight)`,
+ which returns `{ uvOffset, uvScale }` to spread into the `Sprite`. Writing
+ `uvOffset.y = y / height` by hand shows the cell mirrored vertically — invisible on a
+ quad that shows the whole picture, wrong on every atlas cell.
- **Scrolling**: animate `uvOffset` over time to scroll a texture (water, conveyor
belts), and set `tileSize` to repeat it across a large sprite.
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx b/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx
index acd52bcdd..fe3413a10 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx
@@ -327,6 +327,7 @@ world.applyEntityOrder([other, another, card]);
- 用 `flipX` / `flipY` **翻转**精灵——例如让角色朝左或朝右,而不用另一张纹理。
- **图集**:把 `uvOffset` 和 `uvScale` 设为某个单元格的归一化矩形,显示打包图集里的一格;分散的纹理可以用 [`TextureAtlas`](/docs/zh-cn/graphics/drawing/) 在运行时合到一张画布上。(逐帧动画
请用 [Animator](/docs/zh-cn/animation/overview/) 驱动这些,而非手动。)
+- **UV 空间 y 轴向上**:`v = 0` 是图片的*最下面*一行,`v = 1` 是最上面一行,和图片编辑器的像素坐标相反。按左上角为原点量出的像素格子,用 `uvRectFromPixels({ x, y, width, height }, textureWidth, textureHeight)` 换算,返回的 `{ uvOffset, uvScale }` 直接展开进 `Sprite`。手写 `uvOffset.y = y / height` 会让格子上下颠倒——整图铺满一个 quad 时看不出来,取图集格子时每格都错。
- **滚动**:随时间改 `uvOffset` 来滚动纹理(水面、传送带),并设 `tileSize` 把它在大精灵上重复平铺。
## 纹理过滤与环绕
diff --git a/sdk/src/animation/AnimClipLoader.ts b/sdk/src/animation/AnimClipLoader.ts
index 7484382d1..0725f7452 100644
--- a/sdk/src/animation/AnimClipLoader.ts
+++ b/sdk/src/animation/AnimClipLoader.ts
@@ -8,6 +8,7 @@
import type { SpriteAnimClip, SpriteAnimFrame } from './SpriteAnimator';
import { log } from '../util/logger';
+import { uvRectFromPixels } from '../render/uvRect';
import {
sheetCols, sheetRows, sheetCellRect, sheetCellUv, type SheetGrid,
} from '../asset/sheetGrid';
@@ -409,16 +410,7 @@ function uvFromRect(
pageWidth: number,
pageHeight: number,
): Pick<SpriteAnimFrame, 'uvOffset' | 'uvScale'> {
- return {
- uvOffset: {
- x: rect.x / pageWidth,
- y: 1.0 - (rect.y + rect.height) / pageHeight,
- },
- uvScale: {
- x: rect.width / pageWidth,
- y: rect.height / pageHeight,
- },
- };
+ return uvRectFromPixels(rect, pageWidth, pageHeight);
}
/**
diff --git a/sdk/src/asset/sheetGrid.ts b/sdk/src/asset/sheetGrid.ts
index dedf15cb0..0a95cd96a 100644
--- a/sdk/src/asset/sheetGrid.ts
+++ b/sdk/src/asset/sheetGrid.ts
@@ -19,6 +19,8 @@
* already addresses it.
*/
+import { uvRectFromPixels } from '../render/uvRect';
+
/**
* A sheet's cutting geometry, in the image's own pixels. `pageWidth`/`pageHeight`
* are the whole image, which is what turns a pixel rect into a UV window.
@@ -80,15 +82,5 @@ export function sheetCellUv(
grid: SheetGrid,
cell: number,
): { uvOffset: { x: number; y: number }; uvScale: { x: number; y: number } } {
- const rect = sheetCellRect(grid, cell);
- return {
- uvOffset: {
- x: rect.x / grid.pageWidth,
- y: 1.0 - (rect.y + rect.height) / grid.pageHeight,
- },
- uvScale: {
- x: rect.width / grid.pageWidth,
- y: rect.height / grid.pageHeight,
- },
- };
+ return uvRectFromPixels(sheetCellRect(grid, cell), grid.pageWidth, grid.pageHeight);
}
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index a67113890..321f9e655 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -315,6 +315,8 @@ export {
type AtlasEntry,
} from './render/textureAtlas';
+export { uvRectFromPixels, type UvRect } from './render/uvRect';
+
export {
TextureCanvas,
type TextureCanvasHandle,
diff --git a/sdk/src/render/textureAtlas.ts b/sdk/src/render/textureAtlas.ts
index a6cb40ce4..b1c312096 100644
--- a/sdk/src/render/textureAtlas.ts
+++ b/sdk/src/render/textureAtlas.ts
@@ -10,6 +10,7 @@ import { Renderer, onDeviceRestored } from './renderer';
import { RenderTexture, type RenderTextureHandle } from './renderTexture';
import { getResourceManager, getTextureDimensions } from '../wasm/resourceManager';
import { log } from '../util/logger';
+import { uvRectFromPixels } from './uvRect';
/** Where one source texture sits on an atlas. @experimental */
export interface AtlasEntry {
@@ -149,8 +150,7 @@ export const TextureAtlas = {
const { width, height } = sizes[i];
entries.set(source, {
x, y, width, height,
- uvOffset: { x: x / layout.width, y: 1 - (y + height) / layout.height },
- uvScale: { x: width / layout.width, y: height / layout.height },
+ ...uvRectFromPixels({ x, y, width, height }, layout.width, layout.height),
});
});
diff --git a/sdk/src/render/uvRect.ts b/sdk/src/render/uvRect.ts
new file mode 100644
index 000000000..f34a6fd6b
--- /dev/null
+++ b/sdk/src/render/uvRect.ts
@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file render/uvRect.ts
+ * @brief A rectangle of a picture, in pixels, as the UV window a sprite shows.
+ *
+ * Texture space has v growing UP: v = 0 is the image's LAST row, v = 1 its first.
+ * Pixel rectangles (an atlas packer, a sheet grid, an image editor) are measured
+ * from the TOP. The conversion between the two lives here once — written out by
+ * hand it comes out upside down, and a quad that shows the whole picture never
+ * says so.
+ */
+
+/** The window `Sprite.uvOffset` / `uvScale` (and `UIVisual`'s) take. */
+export interface UvRect {
+ uvOffset: { x: number; y: number };
+ uvScale: { x: number; y: number };
+}
+
+/**
+ * The UV window of a pixel rectangle in a @p textureWidth x @p textureHeight
+ * picture, the rectangle's @p y measured DOWN from the top edge as image tools
+ * measure it. Spread the result into a `Sprite` to show exactly that cell.
+ */
+export function uvRectFromPixels(
+ rect: { x: number; y: number; width: number; height: number },
+ textureWidth: number,
+ textureHeight: number,
+): UvRect {
+ return {
+ uvOffset: {
+ x: rect.x / textureWidth,
+ y: 1 - (rect.y + rect.height) / textureHeight,
+ },
+ uvScale: {
+ x: rect.width / textureWidth,
+ y: rect.height / textureHeight,
+ },
+ };
+}