fix(ui): convert viewport sizes with the exact scale ratio (#405)

`View.setDesignResolutionSize` regenerated the visible size with
`viewport / scale`. Because `scale` is itself the rounded `container / design`
quotient, that round trip loses one ULP: a 1080x1920 design on a 1532x1532
viewport produces `1919.9999999999998` instead of `1920`.

Those values are written by `Widget` into `UITransform._contentSize` and
`Node._lpos`, and by `Canvas` into `Camera._orthoHeight`, so the error ends up
in the saved `.scene`/`.prefab` files and makes the editor produce diff churn
whenever it recomputes the layout.

A resolution policy now reports the pair of lengths its scale was derived from
(`pixels`: the container length in device pixels, `units`: the same length in
UI units) instead of the rounded scale, and the viewport is converted with
those two lengths. EXACT_FIT, SHOW_ALL, NO_BORDER, FIXED_HEIGHT and FIXED_WIDTH
all report their pair in place.

The scale is no longer stored anywhere: `AdaptResult` carries `ratioX` /
`ratioY` only, and `getScaleX()` / `getScaleY()` derive `pixels / units` on
demand, so the ratio and the scale cannot diverge.

`toUISpace()` / `toPixelSpace()` are exported next to `ScaleRatio`, and
`View.getRatioX()` / `View.getRatioY()` expose the pair, so any caller can
convert lengths without the lossy `pixels / scale` round trip.

The camera still frames the whole window (`windowSize.height / scaleY / 2`),
but now converts through `toUISpace(size.height, view.getRatioY())`, so a
1532px tall viewport produces exactly 960 instead of 959.9999999999999. No
adaptation, layout or rendering semantics change.

Note for custom resolution policies: `AdaptResult` no longer carries `scale`.
A custom content strategy has to report `ratioX` / `ratioY`; when it does not,
the ratios of the previous policy application are kept and the scale is not
updated. `AdaptResult` and `ContentStrategy` are engine-private classes, so
this only affects strategies passed to `new ResolutionPolicy(...)`.

Co-authored-by: Tianze-Chen <tianze@local>
This commit is contained in:
Tianze-Chen
2026-11-13 11:00:11 +08:00
committed by GitHub
parent 990e3b09aa
commit 62bd937e7e
3 changed files with 283 additions and 47 deletions
+2 -2
View File
@@ -29,7 +29,7 @@ import { EDITOR_NOT_IN_PREVIEW } from 'internal:constants';
import { Camera, CameraEvent } from '../../misc/camera-component';
import { Widget } from '../../ui/widget';
import { Vec3, screen, Enum, cclegacy, visibleRect } from '../../core';
import { view } from '../../ui/view';
import { toUISpace, view } from '../../ui/view';
import { RenderRoot2D } from './render-root-2d';
const _worldPos = new Vec3();
@@ -226,7 +226,7 @@ export class Canvas extends RenderRoot2D {
this._cameraComponent.orthoHeight = visibleRect.height / 2;
} else {
const size = screen.windowSize;
this._cameraComponent.orthoHeight = size.height / view.getScaleY() / 2;
this._cameraComponent.orthoHeight = toUISpace(size.height, view.getRatioY()) / 2;
}
this.node.getWorldPosition(_worldPos);
+107 -45
View File
@@ -56,6 +56,28 @@ import type { Game } from '../game';
const localWinSize = size();
/**
* A pair of equal lengths measured in the two coordinate spaces:
* `pixels` device pixels cover the same distance as `units` UI units, so `scale = pixels / units`.
* Converting between the spaces with those two lengths directly avoids the extra rounding of
* `pixels / scale`, which is off by one ULP in the common case
* (e.g. `1532 / (1532 / 1920) === 1919.9999999999998`).
*/
export interface ScaleRatio {
/** A length in device pixels (the container). */
readonly pixels: number;
/** The same length in UI units (the design resolution). */
readonly units: number;
}
export function toUISpace (value: number, ratio: ScaleRatio): number {
return (value * ratio.units) / ratio.pixels;
}
export function toPixelSpace (value: number, ratio: ScaleRatio): number {
return (value * ratio.pixels) / ratio.units;
}
const orientationMap = {
[macro.ORIENTATION_AUTO]: Orientation.AUTO,
[macro.ORIENTATION_LANDSCAPE]: Orientation.LANDSCAPE,
@@ -69,8 +91,8 @@ export class View extends Eventify(System) {
*/
public _designResolutionSize: Size = size(0, 0); // resolution size, it is the size appropriate for the app resources.
private _scaleX: number = 1;
private _scaleY: number = 1;
private _ratioX: ScaleRatio = { pixels: 1, units: 1 };
private _ratioY: ScaleRatio = { pixels: 1, units: 1 };
private _viewportRect: Rect = rect(); // Viewport is the container's rect related to content's coordinates in pixel
private _visibleRect: Rect = rect(); // The visible rect in content's coordinate in point
private _autoFullScreen: boolean = false; // Auto full screen disabled by default
@@ -352,8 +374,8 @@ export class View extends Eventify(System) {
*/
public getVisibleSizeInPixel (): Size {
return new Size(
this._visibleRect.width * this._scaleX,
this._visibleRect.height * this._scaleY,
toPixelSpace(this._visibleRect.width, this._ratioX),
toPixelSpace(this._visibleRect.height, this._ratioY),
);
}
@@ -371,8 +393,8 @@ export class View extends Eventify(System) {
*/
public getVisibleOriginInPixel (): Vec2 {
return new Vec2(
this._visibleRect.x * this._scaleX,
this._visibleRect.y * this._scaleY,
toPixelSpace(this._visibleRect.x, this._ratioX),
toPixelSpace(this._visibleRect.y, this._ratioY),
);
}
@@ -451,9 +473,9 @@ export class View extends Eventify(System) {
const result = policy.apply(this, this._designResolutionSize);
if (result.scale && result.scale.length === 2) {
this._scaleX = result.scale[0];
this._scaleY = result.scale[1];
if (result.ratioX && result.ratioY) {
this._ratioX = result.ratioX;
this._ratioY = result.ratioY;
}
if (result.viewport) {
@@ -468,8 +490,8 @@ export class View extends Eventify(System) {
vb.x = 0;
vb.y = 0;
vb.width = rv.width / this._scaleX;
vb.height = rv.height / this._scaleY;
vb.width = toUISpace(rv.width, this._ratioX);
vb.height = toUISpace(rv.height, this._ratioY);
}
policy.postApply(this);
@@ -534,7 +556,7 @@ export class View extends Eventify(System) {
* @zh 返回横轴的缩放比,这个缩放比是将画布像素分辨率放到设计分辨率的比例。
*/
public getScaleX (): number {
return this._scaleX;
return this._ratioX.pixels / this._ratioX.units;
}
/**
@@ -542,7 +564,31 @@ export class View extends Eventify(System) {
* @zh 返回纵轴的缩放比,这个缩放比是将画布像素分辨率缩放到设计分辨率的比例。
*/
public getScaleY (): number {
return this._scaleY;
return this._ratioY.pixels / this._ratioY.units;
}
/**
* @en Returns the exact ratio behind `getScaleX()`, use it with `toUISpace()` / `toPixelSpace()`
* to convert lengths without the rounding error of `pixels / getScaleX()`.
* @zh 返回 `getScaleX()` 背后的精确比例,配合 `toUISpace()` / `toPixelSpace()` 换算长度,
* 以避免 `像素 / getScaleX()` 带来的舍入误差。
* @engineInternal
* @mangle
*/
public getRatioX (): ScaleRatio {
return this._ratioX;
}
/**
* @en Returns the exact ratio behind `getScaleY()`, use it with `toUISpace()` / `toPixelSpace()`
* to convert lengths without the rounding error of `pixels / getScaleY()`.
* @zh 返回 `getScaleY()` 背后的精确比例,配合 `toUISpace()` / `toPixelSpace()` 换算长度,
* 以避免 `像素 / getScaleY()` 带来的舍入误差。
* @engineInternal
* @mangle
*/
public getRatioY (): ScaleRatio {
return this._ratioY;
}
/**
@@ -579,14 +625,15 @@ export class View extends Eventify(System) {
}
/**
* Convert location in Cocos screen coordinate to location in UI space
* @en Converts a length from device pixels to UI units, preferring the exact scale ratio.
* @zh 将像素长度换算为 UI 单位长度,优先使用精确比例。
* @engineInternal
* @mangle
*/
public _convertToUISpace (point: Vec2): void {
const viewport = this._viewportRect;
point.x = (point.x - viewport.x) / this._scaleX;
point.y = (point.y - viewport.y) / this._scaleY;
point.x = toUISpace(point.x - viewport.x, this._ratioX);
point.y = toUISpace(point.y - viewport.y, this._ratioY);
}
private _updateAdaptResult (width: number, height: number, windowId?: number): void {
@@ -617,8 +664,9 @@ export class View extends Eventify(System) {
*/
interface AdaptResult {
scale: number[];
viewport?: null | Rect;
ratioX: ScaleRatio;
ratioY: ScaleRatio;
}
/**
@@ -699,8 +747,9 @@ class ContentStrategy {
public name = 'ContentStrategy';
private _result: AdaptResult = {
scale: [1, 1],
viewport: null,
ratioX: { pixels: 1, units: 1 },
ratioY: { pixels: 1, units: 1 },
};
protected _strategy = ResolutionPolicy.UNKNOWN;
@@ -722,13 +771,13 @@ class ContentStrategy {
/**
* @en Function to apply this strategy
* The return value is {scale: [scaleX, scaleY], viewport: {new Rect}},
* The return value is {ratioX, ratioY, viewport: {new Rect}},
* The target view can then apply these value to itself, it's preferred not to modify directly its private variables
* @zh 调用策略方法
* @return The result scale and viewport rect
* @return The exact ratios and the viewport rect
*/
public apply (_view: View, designedResolution: Size): AdaptResult {
return { scale: [1, 1] };
return this._result;
}
/**
@@ -743,7 +792,14 @@ class ContentStrategy {
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
public _buildResult (containerW: number, containerH: number, contentW: number, contentH: number, scaleX: number, scaleY: number): AdaptResult {
public _buildResult (
containerW: number,
containerH: number,
contentW: number,
contentH: number,
ratioX: ScaleRatio,
ratioY: ScaleRatio,
): AdaptResult {
// Makes content fit better the canvas
if (Math.abs(containerW - contentW) < 2) {
contentW = containerW;
@@ -760,8 +816,9 @@ class ContentStrategy {
);
const result = this._result;
result.scale = [scaleX, scaleY];
result.viewport = viewport;
result.ratioX = ratioX;
result.ratioY = ratioY;
return result;
}
}
@@ -819,10 +876,15 @@ class ExactFit extends ContentStrategy {
const windowSize = screen.windowSize;
const containerW = windowSize.width;
const containerH = windowSize.height;
const scaleX = containerW / designedResolution.width;
const scaleY = containerH / designedResolution.height;
return this._buildResult(containerW, containerH, containerW, containerH, scaleX, scaleY);
return this._buildResult(
containerW,
containerH,
containerW,
containerH,
{ pixels: containerW, units: designedResolution.width },
{ pixels: containerH, units: designedResolution.height },
);
}
}
@@ -842,21 +904,21 @@ class ShowAll extends ContentStrategy {
const designH = designedResolution.height;
const scaleX = containerW / designW;
const scaleY = containerH / designH;
let scale = 0;
let contentW: number;
let contentH: number;
let ratio: ScaleRatio;
if (scaleX < scaleY) {
scale = scaleX;
ratio = { pixels: containerW, units: designW };
contentW = containerW;
contentH = designH * scale;
contentH = toPixelSpace(designH, ratio);
} else {
scale = scaleY;
contentW = designW * scale;
ratio = { pixels: containerH, units: designH };
contentW = toPixelSpace(designW, ratio);
contentH = containerH;
}
return this._buildResult(containerW, containerH, contentW, contentH, scale, scale);
return this._buildResult(containerW, containerH, contentW, contentH, ratio, ratio);
}
}
@@ -868,7 +930,7 @@ class NoBorder extends ContentStrategy {
this._strategy = ResolutionPolicy.NO_BORDER;
}
public apply (_view, designedResolution): AdaptResult {
public apply (_view: View, designedResolution: Size): AdaptResult {
const windowSize = screen.windowSize;
const containerW = windowSize.width;
const containerH = windowSize.height;
@@ -876,21 +938,21 @@ class NoBorder extends ContentStrategy {
const designH = designedResolution.height;
const scaleX = containerW / designW;
const scaleY = containerH / designH;
let scale: number;
let contentW: number;
let contentH: number;
let ratio: ScaleRatio;
if (scaleX < scaleY) {
scale = scaleY;
contentW = designW * scale;
ratio = { pixels: containerH, units: designH };
contentW = toPixelSpace(designW, ratio);
contentH = containerH;
} else {
scale = scaleX;
ratio = { pixels: containerW, units: designW };
contentW = containerW;
contentH = designH * scale;
contentH = toPixelSpace(designH, ratio);
}
return this._buildResult(containerW, containerH, contentW, contentH, scale, scale);
return this._buildResult(containerW, containerH, contentW, contentH, ratio, ratio);
}
}
@@ -907,11 +969,11 @@ class FixedHeight extends ContentStrategy {
const containerW = windowSize.width;
const containerH = windowSize.height;
const designH = designedResolution.height;
const scale = containerH / designH;
const contentW = containerW;
const contentH = containerH;
const ratio: ScaleRatio = { pixels: containerH, units: designH };
return this._buildResult(containerW, containerH, contentW, contentH, scale, scale);
return this._buildResult(containerW, containerH, contentW, contentH, ratio, ratio);
}
}
@@ -928,11 +990,11 @@ class FixedWidth extends ContentStrategy {
const containerW = windowSize.width;
const containerH = windowSize.height;
const designW = designedResolution.width;
const scale = containerW / designW;
const contentW = containerW;
const contentH = containerH;
const ratio: ScaleRatio = { pixels: containerW, units: designW };
return this._buildResult(containerW, containerH, contentW, contentH, scale, scale);
return this._buildResult(containerW, containerH, contentW, contentH, ratio, ratio);
}
}
@@ -1026,12 +1088,12 @@ export class ResolutionPolicy {
/**
* @en Function to apply this resolution policy
* The return value is {scale: [scaleX, scaleY], viewport: {new Rect}},
* The return value is {ratioX, ratioY, viewport: {new Rect}},
* The target view can then apply these value to itself, it's preferred not to modify directly its private variables
* @zh 调用策略方法
* @param _view - The target view
* @param designedResolution - The user defined design resolution
* @return An object contains the scale X/Y values and the viewport rect
* @return An object contains the exact ratios and the viewport rect
*/
public apply (_view: View, designedResolution: Size): AdaptResult {
this._containerStrategy.apply(_view, designedResolution);
+174
View File
@@ -0,0 +1,174 @@
import { screen, Size } from '../../cocos/core';
import { UITransform } from '../../cocos/2d/framework/ui-transform';
import { Canvas } from '../../cocos/2d/framework/canvas';
import { Batcher2D } from '../../cocos/2d/renderer/batcher-2d';
import { Camera } from '../../cocos/misc/camera-component';
import { Node } from '../../cocos/scene-graph/node';
import { Scene } from '../../cocos/scene-graph/scene';
import { director } from '../../cocos/game/director';
import { ResolutionPolicy, toPixelSpace, toUISpace, view } from '../../cocos/ui/view';
import { Widget } from '../../cocos/ui/widget';
import { widgetManager } from '../../cocos/ui/widget-manager';
const DESIGN_W = 1080;
const DESIGN_H = 1920;
function mockWindowSize (width: number, height: number): void {
jest.spyOn(screen, 'windowSize', 'get').mockReturnValue(new Size(width, height));
}
function initBatcher (): void {
// @ts-expect-error the batcher is required by Canvas.onEnable in the headless test environment
director.root!._batcher = new Batcher2D(director.root!);
}
function createSceneCanvas (name: string): { node: Node; canvas: Canvas; camera: Camera } {
const scene = new Scene(name);
director.runSceneImmediate(scene);
const node = new Node('Canvas');
scene.addChild(node);
node.addComponent(UITransform);
const canvas = node.addComponent(Canvas) as Canvas;
const camNode = new Node('UICamera');
camNode.parent = node;
const camera = camNode.addComponent(Camera) as Camera;
canvas.cameraComponent = camera;
(canvas as unknown as { _onResizeCamera(): void })._onResizeCamera();
return { node, canvas, camera };
}
afterEach(() => {
jest.restoreAllMocks();
});
describe('scale ratio keeps UI lengths exact', () => {
test('FIXED_HEIGHT: the fitted axis equals the design size instead of 1919.9999999999998', () => {
mockWindowSize(1532, 1532); // the viewport from the packaged-editor report
view.setDesignResolutionSize(DESIGN_W, DESIGN_H, ResolutionPolicy.FIXED_HEIGHT);
const visible = view.getVisibleSize();
expect(visible.height).toBe(1920);
expect(visible.width).toBe(1920); // adapted axis, exactly representable
const pixel = view.getVisibleSizeInPixel();
expect(pixel.width).toBe(1532); // the round trip back to pixels stays exact
expect(pixel.height).toBe(1532);
// the rounded scale is untouched, it is only no longer used for the conversion
expect(view.getScaleY()).toBe(1532 / 1920);
});
test('FIXED_HEIGHT: the canvas camera keeps 960 instead of 959.9999999999999', () => {
mockWindowSize(1532, 1532);
view.setDesignResolutionSize(DESIGN_W, DESIGN_H, ResolutionPolicy.FIXED_HEIGHT);
initBatcher();
const { camera } = createSceneCanvas('ratio-camera-fixed-height');
expect(camera.orthoHeight).toBe(960);
});
test('FIXED_WIDTH: both axes are exact', () => {
mockWindowSize(1024, 768);
view.setDesignResolutionSize(DESIGN_W, DESIGN_H, ResolutionPolicy.FIXED_WIDTH);
initBatcher();
const visible = view.getVisibleSize();
expect(visible.width).toBe(1080);
expect(visible.height).toBe(810);
const { camera } = createSceneCanvas('ratio-camera-fixed-width');
expect(camera.orthoHeight).toBe(405);
});
test('SHOW_ALL: the visible size equals the design resolution', () => {
mockWindowSize(1024, 768);
view.setDesignResolutionSize(DESIGN_W, DESIGN_H, ResolutionPolicy.SHOW_ALL);
const visible = view.getVisibleSize();
expect(visible.width).toBe(1080);
expect(visible.height).toBe(1920);
});
test('EXACT_FIT: the visible size equals the design resolution', () => {
mockWindowSize(1024, 768);
view.setDesignResolutionSize(DESIGN_W, DESIGN_H, ResolutionPolicy.EXACT_FIT);
const visible = view.getVisibleSize();
expect(visible.width).toBe(1080);
expect(visible.height).toBe(1920);
});
test('NO_BORDER: the visible size equals the design resolution while the content is cropped', () => {
mockWindowSize(1024, 3840);
view.setDesignResolutionSize(DESIGN_W, DESIGN_H, ResolutionPolicy.NO_BORDER);
const visible = view.getVisibleSize();
expect(visible.width).toBe(1080);
expect(visible.height).toBe(1920);
});
test('the reported ratio converts lengths in both directions without error', () => {
mockWindowSize(1532, 1532);
view.setDesignResolutionSize(DESIGN_W, DESIGN_H, ResolutionPolicy.FIXED_HEIGHT);
const ratio = view.getRatioY();
expect(ratio.pixels).toBe(1532);
expect(ratio.units).toBe(1920);
expect(toUISpace(1532, ratio)).toBe(1920);
expect(toPixelSpace(1920, ratio)).toBe(1532);
});
test('EXACT_FIT: the derived scale factors stay bit-identical to the policy scale', () => {
mockWindowSize(1024, 768);
view.setDesignResolutionSize(DESIGN_W, DESIGN_H, ResolutionPolicy.EXACT_FIT);
// The scale is no longer stored, it is derived from the exact ratio on demand.
expect(view.getScaleX()).toBe(1024 / 1080);
expect(view.getScaleY()).toBe(768 / 1920);
});
test('setting the same resolution twice is idempotent', () => {
mockWindowSize(1532, 1532);
view.setDesignResolutionSize(DESIGN_W, DESIGN_H, ResolutionPolicy.FIXED_HEIGHT);
const first = { visible: view.getVisibleSize(), scale: view.getScaleY() };
view.setDesignResolutionSize(DESIGN_W, DESIGN_H, ResolutionPolicy.FIXED_HEIGHT);
expect(view.getVisibleSize().width).toBe(first.visible.width);
expect(view.getVisibleSize().height).toBe(first.visible.height);
expect(view.getScaleY()).toBe(first.scale);
});
test('a root widget gets the exact canvas size and position', () => {
mockWindowSize(1532, 1532);
view.setDesignResolutionSize(DESIGN_W, DESIGN_H, ResolutionPolicy.FIXED_HEIGHT);
initBatcher();
const scene = new Scene('ratio-widget');
director.runSceneImmediate(scene);
const node = new Node('Canvas');
scene.addChild(node);
node.addComponent(UITransform);
node.addComponent(Canvas);
const widget = node.addComponent(Widget) as Widget;
widget.isAlignLeft = true;
widget.isAlignRight = true;
widget.isAlignTop = true;
widget.isAlignBottom = true;
widget.left = 0;
widget.right = 0;
widget.top = 0;
widget.bottom = 0;
widgetManager.updateAlignment(node);
const trans = node.getComponent(UITransform) as UITransform;
expect(trans.width).toBe(1920);
expect(trans.height).toBe(1920);
expect(node.position.x).toBe(960);
expect(node.position.y).toBe(960);
});
});