mirror of
https://github.com/cocos/cocos4.git
synced 2026-11-20 23:52:40 +08:00
f570c1f02d
* feat(pal): declare startup maximum DPR configuration Add an optional maximum DPR to screen initialization and readonly access to the original DPR and explicitly configured cap. An omitted or null cap retains the platform's existing policy. This is the engine type contract for the staged PAL implementation. Public Screen configuration methods and Native render-target integration remain separate work; this commit does not change runtime rendering. Validated against the PAL engine/four-platform contract check and full npm test (65 source tests, 4 build tests, release/debug module validation). * feat(screen): expose startup maximum DPR configuration Allow applications to set, reset and read a pending maximum DPR before Screen initialization while preserving platform defaults when unconfigured. Lock the configuration at initialization and reject unsupported PAL implementations or options that PAL silently ignores. Add startup validation and compatibility tests. Only implementation and tests are included; local documentation and generated validation artifacts remain outside this commit. Companion PAL commit: 2959778b7acf83dd84e3aab5957d60d80e20c461. Native render-target integration, device acceptance, runtime changes and editor configuration remain separate work. Validation recorded on 2026-09-29: tsc --noEmit; 20 Screen and 6 View tests; public declaration generation; real WebGL demo with simulated host DPR, first-draw, input, reset, late-call rejection and resize checks. Screen source SHA-256 still matches that verified build. * fix(screen): restrict startup DPR configuration to Web * fix(screen): ignore DPR cap calls on non-Web platforms * fix(screen): preserve optional DPR types in native builds * refactor(screen): configure Web DPR through startup settings * refactor(screen): delegate DPR policy and validation to PAL * style(screen): wrap fullscreen method signatures * perf(screen): simplify startup DPR null checks * version update
135 lines
5.3 KiB
TypeScript
135 lines
5.3 KiB
TypeScript
declare module 'pal/screen-adapter' {
|
|
export interface SafeAreaEdge {
|
|
top: number;
|
|
bottom: number;
|
|
left: number;
|
|
right: number;
|
|
}
|
|
|
|
export type ConfigOrientation = 'auto' | 'landscape' | 'portrait';
|
|
export interface IScreenOptions {
|
|
/**
|
|
* Orientation options from editor builder.
|
|
*/
|
|
configOrientation: ConfigOrientation;
|
|
/**
|
|
* Determine whether the game frame exact fits the screen.
|
|
* Now it only works on Web platform.
|
|
*/
|
|
exactFitScreen: boolean;
|
|
|
|
/**
|
|
* Determine whether use headless renderer, which means do not support some screen operations.
|
|
*/
|
|
isHeadlessMode: boolean;
|
|
/**
|
|
* Optional startup DPR cap, currently consumed by Web.
|
|
* Supporting adapters validate that it is finite and >= 1; other adapters ignore it.
|
|
* Omission/null preserves the adapter's default policy (Web caps DPR at 2).
|
|
*/
|
|
maxDevicePixelRatio?: number | null;
|
|
}
|
|
|
|
class ScreenAdapter {
|
|
/**
|
|
* Init the callback to rebuild frame buffer when update the resolution.
|
|
* This method will also init the resolution.
|
|
* This method should be called when the engine director.root is initiated.
|
|
* @param options
|
|
* @param cbToRebuildFrameBuffer
|
|
*/
|
|
public init (options: IScreenOptions, cbToRebuildFrameBuffer: () => void);
|
|
/**
|
|
* On web mobile platform, sometimes we need to rotate the game frame.
|
|
* This field record the rotate state of game frame, which is false by default.
|
|
*/
|
|
public isFrameRotated: boolean;
|
|
/**
|
|
* On web platform, we support to set container strategy.
|
|
* This field record whether we apply ProportionalToFrame strategy on container, which is false by default.
|
|
*/
|
|
public get isProportionalToFrame (): boolean;
|
|
public set isProportionalToFrame (v: boolean);
|
|
/**
|
|
* In some case we don't want to handle the resize event.
|
|
* For example, when the soft keyboard shows up, we don't want to resize the canvas.
|
|
* This is true by default.
|
|
*/
|
|
public handleResizeEvent: boolean;
|
|
/**
|
|
* Query whether fullscreen feature is supported on the current platform.
|
|
*/
|
|
public get supportFullScreen (): boolean;
|
|
/**
|
|
* Query the current fullscreen state.
|
|
*/
|
|
public get isFullScreen (): boolean;
|
|
/**
|
|
* Optional capability: the applied startup cap, or null for the adapter's default.
|
|
* Adapters exposing this property consume and validate maxDevicePixelRatio.
|
|
* Absent on adapters that ignore this setting.
|
|
*/
|
|
public readonly maxDevicePixelRatio?: number | null;
|
|
/**
|
|
* The ratio of pixel sizes:
|
|
* the size of one CSS pixel to the size of one physical pixel.
|
|
*/
|
|
public get devicePixelRatio (): number;
|
|
/**
|
|
* Get the size of current window in physical pixels.
|
|
*/
|
|
|
|
/**
|
|
* Get and set the size of current window in physical pixels.
|
|
*/
|
|
public get windowSize (): import('cocos/core/math').Size;
|
|
public set windowSize (size: import('cocos/core/math').Size);
|
|
|
|
/**
|
|
* Get the current resolution of game.
|
|
* This is a readonly property, you can change the value by setting screenAdapter.resolutionScale.
|
|
*/
|
|
public get resolution (): import('cocos/core/math').Size;
|
|
|
|
/**
|
|
* Get and set the resolution scale of screen, which will affect the quality of the rendering.
|
|
* Note: if this value is set too high, the rendering performance of GPU will be reduced, this value is 1 by default.
|
|
*/
|
|
public get resolutionScale (): number;
|
|
public set resolutionScale (value: number);
|
|
|
|
/**
|
|
* Get or set the orientation of current game.
|
|
* Available on mobile related platform for now.
|
|
*/
|
|
public get orientation (): import('pal/screen-adapter/enum-type').Orientation;
|
|
public set orientation (value: import('pal/screen-adapter/enum-type').Orientation);
|
|
|
|
/**
|
|
* Get the SafeAreaEdge based on the screen coordinate system in physical pixels.
|
|
* @return {SafeAreaEdge} An interface displaying the distance of the sides 'top', 'bottom', 'left' and 'right'.
|
|
*/
|
|
public get safeAreaEdge (): SafeAreaEdge;
|
|
|
|
/**
|
|
* Asynchronously request fullscreen
|
|
* If failed to request fullscreen, another attempt will be made to request fullscreen the next time a user interaction occurs.
|
|
* @returns Promise to request fullscreen
|
|
*/
|
|
public requestFullScreen (): Promise<void>;
|
|
/**
|
|
* Asynchronously exit fullscreen
|
|
* @returns Promise to exit fullscreen
|
|
*/
|
|
public exitFullScreen (): Promise<void>;
|
|
|
|
on (event: import('pal/screen-adapter/enum-type').PalScreenEvent, cb: (...args: any) => void, target?: any);
|
|
once (event: import('pal/screen-adapter/enum-type').PalScreenEvent, cb: (...args: any) => void, target?: any);
|
|
off (event: import('pal/screen-adapter/enum-type').PalScreenEvent, cb?: (...args: any) => void, target?: any);
|
|
}
|
|
|
|
export const screenAdapter: ScreenAdapter;
|
|
|
|
export {};
|
|
}
|