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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.mdxindex 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, conveyorbelts), 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.mdxindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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,+ },+ };+}