org.eframework.uni.util
Version:
EFramework Utility for Unite 是一个轻量级、跨平台的工具集，提供了统一的 API 接口，确保在多平台环境下保持一致的运行结果。
1,256 lines • 3.16 MB
TypeScript
/**
* @zh
* 基于 Cocos Creator 3.8.4 接口。
* @en
* Based on Cocos Creator 3.8.4 api.
*/
declare namespace cc {
/**
* @en
* Predefined constants, see [[Macro]] for detailed contents.
* @zh
* 预定义常量，具体内容参考 [[Macro]] 文档。
*/
export const macro: Macro;
/**
* @en
* Predefined constants, see [[Macro]] for detailed contents.
* @zh
* 预定义常量，具体内容参考 [[Macro]] 文档。
*/
/**
* @en Interface declaration for predefined constants, for usage you should be importing [[macro]] directly.
* @zh 预定义常量的接口声明，实际使用应该直接导入 [[macro]]。
*/
export interface Macro {
/**
* @en
* The image format supported by the engine, the actual supported formats may differ in different build platforms and device types.
* Currently contains ['.astc', '.pkm', '.pvr', '.webp', '.jpg', '.jpeg', '.bmp', '.png'].
* @zh
* 引擎默认支持的图片格式，实际运行时支持的格式可能在不同的构建平台和设备类型上有所差别。
* 目前包含的格式有 ['.astc', '.pkm', '.pvr', '.webp', '.jpg', '.jpeg', '.bmp', '.png']。
*/
SUPPORT_TEXTURE_FORMATS: string[];
/**
* @en Key map for keyboard event
* @zh 键盘事件的按键值。
* @example {@link cocos/core/platform/CCCommon/KEY.js}
* @deprecated since v3.3 please use [[KeyCode]] instead
*/
KEY: typeof __private._cocos_core_platform_macro__KEY;
/**
* @en One angle in radian, equals to PI / 180
* @zh 弧度制中的单位角度，等同于 PI / 180
*/
RAD: number;
/**
* @en One radian in angle, equals to 180 / PI
* @zh 角度制中的单位弧度，等同于 180 / PI
*/
DEG: number;
/**
* @en A maximum value of number representing infinity repeat times
* @zh 重复执行的最大值，实际取值为数字的最大值
*/
REPEAT_FOREVER: number;
/**
* @en A float value for representing a minimum error in comparison
* @zh 用于比较时可忽略的浮点误差值
*/
FLT_EPSILON: number;
/**
* @en Oriented vertically
* @zh 竖屏朝向
*/
ORIENTATION_PORTRAIT: number;
/**
* @en Inverted portrait orientation, with the device bottom facing upward.
* @zh 倒置竖屏，设备底部朝上
*/
ORIENTATION_PORTRAIT_UPSIDE_DOWN: number;
/**
* @en Oriented horizontally. Users cannot directly listen to this value; they need to listen for ORIENTATION_LANDSCAPE_LEFT or ORIENTATION_LANDSCAPE_RIGHT.
* @zh 横屏朝向, 外部不能直接监听该值，需要监听 ORIENTATION_LANDSCAPE_LEFT 或 ORIENTATION_LANDSCAPE_RIGHT
*/
ORIENTATION_LANDSCAPE: number;
/**
* @en Oriented horizontally, top side facing to the left. Supported only on mobile devices.
* @zh 水平方向，顶部朝向左侧;仅移动端支持
*/
ORIENTATION_LANDSCAPE_LEFT: number;
/**
* @en Oriented horizontally, top side facing to the right. Supported only on mobile devices.
* @zh 水平方向，顶部朝向右侧;仅移动端支持
*/
ORIENTATION_LANDSCAPE_RIGHT: number;
/**
* @en Oriented automatically
* @zh 自动适配朝向
*/
ORIENTATION_AUTO: number;
/**
* @en
* Whether or not enabled tiled map auto culling. If you set the TiledMap skew or rotation,
* then need to manually disable this, otherwise, the rendering will be wrong.
* Currently not used in 3D engine
* @zh
* 是否开启瓦片地图的自动裁减功能。瓦片地图如果设置了 skew, rotation 的话，需要手动关闭，否则渲染会出错。
* 在 3D 引擎中暂时无效。
* @default true
* @deprecated since v3.0
*/
ENABLE_TILEDMAP_CULLING: boolean;
/**
* @en
* The timeout to determine whether a touch is no longer active and should be removed.
* The reason to add this timeout is due to an issue in X5 browser core,
* when X5 is presented in wechat on Android, if a touch is glissed from the bottom up, and leave the page area,
* no touch cancel event is triggered, and the touch will be considered active forever.
* After multiple times of this action, our maximum touches number will be reached and all new touches will be ignored.
* So this new mechanism can remove the touch that should be inactive if it's not updated during the last 5000 milliseconds.
* Though it might remove a real touch if it's just not moving for the last 5 seconds,
* which is not easy with the sensibility of mobile touch screen.
* You can modify this value to have a better behavior if you find it's not enough.
* @zh
* 用于甄别一个触点对象是否已经失效并且可以被移除的延时时长
* 添加这个时长的原因是 X5 内核在微信浏览器中出现的一个 bug。
* 在这个环境下，如果用户将一个触点从底向上移出页面区域，将不会触发任何 touch cancel 或 touch end 事件，而这个触点会被永远当作停留在页面上的有效触点。
* 重复这样操作几次之后，屏幕上的触点数量将达到我们的事件系统所支持的最高触点数量，之后所有的触摸事件都将被忽略。
* 所以这个新的机制可以在触点在一定时间内没有任何更新的情况下视为失效触点并从事件系统中移除。
* 当然，这也可能移除一个真实的触点，如果用户的触点真的在一定时间段内完全没有移动（这在当前手机屏幕的灵敏度下会很难）。
* 你可以修改这个值来获得你需要的效果，默认值是 5000 毫秒。
* @default 5000
*/
TOUCH_TIMEOUT: number;
/**
* @en
* Boolean that indicates if the canvas contains an alpha channel, default sets to false for better performance.
* Though if you want to make your canvas background transparent and show other dom elements at the background,
* you can set it to true before [[game.init]].
* Web only.
* @zh
* 用于设置 Canvas 背景是否支持 alpha 通道，默认为 false，这样可以有更高的性能表现。
* 如果你希望 Canvas 背景是透明的，并显示背后的其他 DOM 元素，你可以在 [[game.init]] 之前将这个值设为 true。
* 仅支持 Web
* @default false
*/
ENABLE_TRANSPARENT_CANVAS: boolean;
/**
* @en
* Boolean that indicates if the GL context is created with `antialias` option turned on, default value is false.
* Set it to true could make your game graphics slightly smoother, like texture hard edges when rotated.
* Whether to use this really depend on your game design and targeted platform,
* device with retina display usually have good detail on graphics with or without this option,
* you probably don't want antialias if your game style is pixel art based.
* Also, it could have great performance impact with some browser / device using software MSAA.
* You can set it to true before [[game.init]].
* Only affect OpenGL ES and WebGL backend
* @zh
* 用于设置在创建 GL Context 时是否开启抗锯齿选项，默认值是 false。
* 将这个选项设置为 true 会让你的游戏画面稍稍平滑一些，比如旋转硬边贴图时的锯齿。是否开启这个选项很大程度上取决于你的游戏和面向的平台。
* 在大多数拥有 retina 级别屏幕的设备上用户往往无法区分这个选项带来的变化；如果你的游戏选择像素艺术风格，你也多半不会想开启这个选项。
* 同时，在少部分使用软件级别抗锯齿算法的设备或浏览器上，这个选项会对性能产生比较大的影响。
* 你可以在 [[game.init]] 之前设置这个值，否则它不会生效。
* 仅影响 WebGL 后端
* @default true
*/
ENABLE_WEBGL_ANTIALIAS: boolean;
/**
* @en
* Used to set float output render target, more accurate multiple light sources, fog, and translucent effects, custom pipeline only, the default value is false.
* @zh
* 用于开启浮点格式的RT输出, 更精确的多光源、雾化和半透明效果, 仅用于自定义管线, 默认值为 false。
* @default false
*/
ENABLE_FLOAT_OUTPUT: boolean;
/**
* @en
* Whether to clear the original image cache after uploaded a texture to GPU.
* If cleared, [Dynamic Atlas](https://docs.cocos.com/creator/manual/en/advanced-topics/dynamic-atlas.html) will not be supported.
* Normally you don't need to enable this option on the web platform, because Image object doesn't consume too much memory.
* But on Wechat Game platform, the current version cache decoded data in Image object, which has high memory usage.
* So we enabled this option by default on Wechat, so that we can release Image cache immediately after uploaded to GPU.
* Currently not useful in 3D engine
* @zh
* 是否在将贴图上传至 GPU 之后删除原始图片缓存，删除之后图片将无法进行 [动态合图](https://docs.cocos.com/creator/manual/zh/advanced-topics/dynamic-atlas.html)。
* 在 Web 平台，你通常不需要开启这个选项，因为在 Web 平台 Image 对象所占用的内存很小。
* 但是在微信小游戏平台的当前版本，Image 对象会缓存解码后的图片数据，它所占用的内存空间很大。
* 所以我们在微信平台默认开启了这个选项，这样我们就可以在上传 GL 贴图之后立即释放 Image 对象的内存，避免过高的内存占用。
* 在 3D 引擎中暂时无效。
* @default false
*/
CLEANUP_IMAGE_CACHE: boolean;
/**
* @en
* Whether to enable multi-touch.
* @zh
* 是否开启多点触摸
* @default true
*/
ENABLE_MULTI_TOUCH: boolean;
/**
* @en
* The maximum size of the canvas pool used by Label, please adjust according to the number of label component in the same scene of the project
* @zh
* Label 使用的 canvas pool 的最大大小，请根据项目同场景的 label 数量进行调整
* @default 20
*/
MAX_LABEL_CANVAS_POOL_SIZE: number;
/**
* @en
* Boolean that indicates if enable highp precision data in structure with fragment shader.
* Enable this option will make the variables defined by the HIGHP_VALUE_STRUCT_DEFINE macro in the shader more accurate, such as position.
* Enable this option can avoid some distorted lighting effects. That depends on whether your game has abnormal lighting effects on this platform.
* There will be a slight performance loss if enable this option, but the impact is not significant.
* Only affect WebGL backend
* @zh
* 用于设置是否在片元着色器中使用结构体的时候，允许其中的数据使用highp精度
* 将这个选项设置为 true 会让shader中使用HIGHP_VALUE_STRUCT_DEFINE宏定义的变量精度更高，比如位置信息等，避免出现一些失真的光照效果。是否开启这个选项很大程度上取决于你的游戏在此平台上是否出现了异常的表现。
* 开启后会有轻微的性能损失，但影响不大。
* 仅影响 WebGL 后端
* @default false
*/
ENABLE_WEBGL_HIGHP_STRUCT_VALUES: boolean;
/**
* @zh Batcher2D 中内存增量的大小（KB）
* 这个值决定了当场景中存在的 2d 渲染组件的顶点数量超过当前 batcher2D 中可容纳的顶点数量时，内存扩充的增加量
* 这个值越大，共用同一个 meshBuffer 的 2d 渲染组件数量会更多，但每次扩充所占用的内存也会更大
* 默认值在标准格式（[[VertexFormat.vfmtPosUvColor]]）下可容纳 4096 个顶点（4096*9*4/1024），你可以增加容量来提升每个批次可容纳的元素数量
* @en The MeshBuffer chunk size in Batcher2D (KB)
* This value determines the increase in memory expansion,
* when the number of vertices of 2d rendering components present in the scene exceeds the number of vertices,
* that can be accommodated in the current batcher2D.
* The larger this value is, the more 2d rendering components will share the same meshBuffer, but the more memory will be used for each expansion
* The default size can contain 4096 standard vertex ([[VertexFormat.vfmtPosUvColor]]) in one buffer,
* you can user larger buffer size to increase the elements count per 2d draw batch.
* @default 144 KB
*/
BATCHER2D_MEM_INCREMENT: number;
/**
* @zh 自定义渲染管线的名字（实验性）
* 引擎会根据名字创建对应的渲染管线（仅限Web平台）。如果名字为空，则不启用自定义渲染管线。
* 目前仅支持'Forward', 'Deferred'两种。
* @en The name of custom rendering pipeline (experimental)
* Engine will use the name to create the custom pipeline (Web only). If the name is empty, custom pipeline will be disabled.
* Currently only 'Forward' and 'Deferred' are supported.
*/
CUSTOM_PIPELINE_NAME: string;
/**
* @internal
*/
init(): void;
}
/**
* @en JS Implementation of MurmurHash2. Original implementation is http://github.com/garycourt/murmurhash-js.
* @zh MurmurHash2 的 JS 实现。原始实现是 http://github.com/garycourt/murmurhash-js 。
* @param input @en ASCII string or a Uint8Array to be hashed. @zh 希望被哈希的 ASCII 字符串或者 Uint8Array.
* @param seed @en Hash seed. Should be a positive integer. @zh 哈希种子。必须是个正整数。
* @returns @en 32-bit positive integer hash. @zh 32位正整数哈希值。
*/
export function murmurhash2_32_gc(input: string | Uint8Array, seed: number): number;
export class ReflectionProbeManager {
static probeManager: ReflectionProbeManager;
/**
* @en Set and get whether to detect objects leaving or entering the reflection probe's bounding box at runtime.
* @zh 设置和获取是否在运行时检测物体离开或者进入反射探针的包围盒。
*/
set updateForRuntime(val: boolean);
get updateForRuntime(): boolean;
/**
* @en Refresh all reflection probe.
* @zh 刷新所有反射探针。
*/
onUpdateProbes(): void;
/**
* @en filter models that use planar reflection.
* @zh 筛选使用平面反射的模型
*/
filterModelsForPlanarReflection(): void;
/**
* @en Get all reflection probes in the scene.
* @zh 获取场景中所有的反射探针
*/
getProbes(): renderer.scene.ReflectionProbe[];
/**
* @en Get reflection probe by id.
* @zh 根据id获取反射探针
*/
getProbeById(probeId: number): renderer.scene.ReflectionProbe | null;
/**
* @en Update the cubemap captured by the reflection probe.
* @zh 更新反射探针捕获的cubemap
* @param probe update the texture for this probe
*/
updateBakedCubemap(probe: renderer.scene.ReflectionProbe): void;
/**
* @en Update the plane reflection map for reflection probe render.
* @zh 更新反射探针渲染的平面反射贴图
* @param probe update the texture for this probe
*/
updatePlanarMap(probe: renderer.scene.ReflectionProbe, texture: gfx.Texture | null): void;
/**
* @en Selecting the appropriate reflection probe for the model, it will use the closest one based on distance.
* @zh 为模型选择适用的反射探针，会使用距离最近的。
* @param model select for this model
*/
selectReflectionProbe(model: renderer.scene.Model): void;
/**
* @en Update the preview sphere of the Reflection Probe cube mode.
* @zh 更新反射探针cube模式的预览球
*/
updatePreviewSphere(probe: renderer.scene.ReflectionProbe): void;
/**
* @en Update the preview plane of the Reflection Probe planar mode.
* @zh 更新反射探针预览平面
*/
updatePreviewPlane(probe: renderer.scene.ReflectionProbe): void;
/**
* @en Update reflection probe data of model bind.
* @zh 更新模型绑定的反射探针数据。
*/
updateProbeData(): void;
/**
* @en get max value of probe id.
* @zh 获取反射探针id的最大值。
*/
getMaxProbeId(): number;
/**
* @en Get the reflection probe used by the model.
* @zh 获取模型使用的反射探针。
*/
getUsedReflectionProbe(model: renderer.scene.Model, planarReflection: boolean): renderer.scene.ReflectionProbe | null | undefined;
/**
* @en Set reflection probe used by the model.
* @zh 手动设置模型使用的反射探针。
* @param model set the probe for this model
* @param probe reflection probe to be set
* @param blendProbe reflection probe for blend
*/
setReflectionProbe(model: renderer.scene.Model, probe: renderer.scene.ReflectionProbe, blendProbe?: renderer.scene.ReflectionProbe | null): void;
}
/**
* @en Mesh buffer used for 2d rendering, used internally and not of concern to the user.
* @zh 2d 渲染使用的网格缓冲数据，内部使用，用户不须关心。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
export class MeshBuffer {
/**
* @en The vertex attributes of the buffer.
* @zh buffer 的顶点属性。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get attributes(): gfx.Attribute[];
/**
* @en Number of bytes in vertex format.
* @zh 顶点格式的字节数。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get vertexFormatBytes(): number;
protected _byteOffset: number;
/**
* @en byte offset.
* @zh 字节偏移量。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get byteOffset(): number;
set byteOffset(val: number);
protected _vertexOffset: number;
/**
* @en Vertexes offset.
* @zh 顶点数偏移。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get vertexOffset(): number;
set vertexOffset(val: number);
protected _indexOffset: number;
/**
* @en Indices offset.
* @zh 索引偏移。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get indexOffset(): number;
set indexOffset(val: number);
protected _dirty: boolean;
/**
* @en Dirty flag.
* @zh 脏标记。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get dirty(): boolean;
set dirty(val: boolean);
protected _floatsPerVertex: number;
/**
* @en Float numbers per vertex.
* @zh 每顶点的浮点数长度。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get floatsPerVertex(): number;
set floatsPerVertex(val: number);
protected _vData: Float32Array;
/**
* @en Vertexes data.
* @zh 顶点数据。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get vData(): Float32Array;
set vData(val: Float32Array);
protected _iData: Uint16Array;
/**
* @en Indices data.
* @zh 索引数据。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get iData(): Uint16Array;
set iData(val: Uint16Array);
protected _nativeObj: __private._cocos_2d_renderer_native_2d__NativeUIMeshBuffer;
/**
* @en Native object.
* @zh 原生对象。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get nativeObj(): __private._cocos_2d_renderer_native_2d__NativeUIMeshBuffer;
protected _sharedBuffer: Uint32Array;
/**
* @en Native shared buffer.
* @zh 原生共享缓冲。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get sharedBuffer(): Uint32Array;
/**
* @en Initial native shared buffer.
* @zh 初始化原生共享缓冲。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
initSharedBuffer(): void;
/**
* @en Synchronized native shared buffer.
* @zh 同步原生共享缓冲。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
syncSharedBufferToNative(): void;
constructor();
/**
* @en Initialize mesh buffer.
* @zh 初始化对象。
* @param device @en The GFX device. @zh GFX设备。
* @param attrs @en The vertex attributes of the buffer. @zh 缓冲区的顶点属性。
* @param vFloatCount @en The vertexes float count. @zh 每顶点所需的 float 数量。
* @param iCount @en The indices count. @zh 索引数量。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
initialize(device: gfx.Device, attrs: gfx.Attribute[], vFloatCount: number, iCount: number): void;
/**
* @en Reset state.
* @zh 重置状态。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
reset(): void;
destroy(): void;
/**
* @en Set dirty flag.
* @zh 设置脏标签。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
setDirty(): void;
/**
* @deprecated since v3.4.0, please use BufferAccessor's request
* @see [[BufferAccessor.request]]
*/
request(vertexCount: number, indexCount: number): boolean;
/**
* @en require Free input assembler.
* @zh 请求可用的输入汇集器。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
requireFreeIA(device: gfx.Device): gfx.InputAssembler;
/**
* @en recycle input assembler.
* @zh 回收输入汇集器。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
recycleIA(ia: gfx.InputAssembler): void;
/**
* @en check capacity.
* @zh 检查可分配余量。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
checkCapacity(vertexCount: number, indexCount: number): boolean;
/**
* @en Upload and update buffers data.
* @zh 上传更新缓冲内容。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
uploadBuffers(): void;
}
/**
* @en Stencil state manager.
* @zh 模板状态管理器。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
export class StencilManager {
static sharedManager: StencilManager | null;
/**
* @en Stencil stage.
* @zh 模板缓冲阶段。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get stage(): __private._cocos_2d_renderer_stencil_manager__Stage;
set stage(val: __private._cocos_2d_renderer_stencil_manager__Stage);
/**
* @en Stencil pattern.
* @zh 模板缓冲样式。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get pattern(): {
stencilTest: boolean;
func: gfx.ComparisonFunc;
stencilMask: number;
writeMask: number;
failOp: gfx.StencilOp;
zFailOp: gfx.StencilOp;
passOp: gfx.StencilOp;
ref: number;
};
/**
* @en Add mask nesting.
* @zh 添加mask嵌套。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
pushMask(mask: any): void;
/**
* @en clear stencil stage.
* @zh 清空模板状态。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
clear(comp: UIRenderer | UIMeshRenderer): __private._cocos_2d_renderer_stencil_manager__Stage;
/**
* @en Open stencil stage to enabled.
* @zh 开启模板状态。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
enableMask(): void;
/**
* @en exit stencil.
* @zh 退出模板状态。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
exitMask(): void;
/**
* @en Get write mask count.
* @zh 获取写入模板缓冲的位数。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
getWriteMask(): number;
/**
* @en Get write mask count when exit.
* @zh 获取退出时模板缓冲的位数。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
getExitWriteMask(): number;
/**
* @en Get mask nesting count.
* @zh 获取mask嵌套数量。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
getMaskStackSize(): number;
/**
* @en Reset stencil stage.
* @zh 重置模板状态。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
reset(): void;
destroy(): void;
/**
* @en Get stencil stage.
* @zh 获取模板状态。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
getStencilStage(stage: __private._cocos_2d_renderer_stencil_manager__Stage, mat?: Material): gfx.DepthStencilState;
/**
* @en Get stencil hash.
* @zh 获取模板状态的哈希值。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
getStencilHash(stage: __private._cocos_2d_renderer_stencil_manager__Stage): number;
}
export const spriteAssembler: IAssemblerManager;
export const labelAssembler: IAssemblerManager;
export const graphicsAssembler: IAssemblerManager;
/**
* @en
* Class for sprite atlas handling.
* @zh
* 精灵图集资源类。
*/
export class SpriteAtlas extends Asset {
/**
* @en All sprite frames in the sprite atlas.
* @zh 精灵图集中的所有精灵。
*/
spriteFrames: __private._cocos_2d_assets_sprite_atlas__ISpriteFrameList;
constructor();
/**
* @en Get the [[Texture2D]] asset of the atlas.
* @zh 获取精灵图集的贴图。
* @returns @en The texture2d asset. @zh 二维贴图资源。
*/
getTexture(): __private._cocos_asset_assets_texture_base__TextureBase | null;
/**
* @en Gets the [[SpriteFrame]] correspond to the given key in sprite atlas.
* @zh 根据键值获取精灵。
*
* @param key @en The SpriteFrame name. @zh 精灵名字。
* @returns @en The SpriteFrame asset. @zh 精灵资源。
*/
getSpriteFrame(key: string): SpriteFrame | null;
/**
* @en Returns all sprite frames in the sprite atlas.
* @zh 获取精灵图集所有精灵。
* @returns @en All sprite frames. @zh 所有的精灵资源。
*/
getSpriteFrames(): (SpriteFrame | null)[];
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
_serialize(ctxForExporting: any): any;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
_deserialize(serializeData: any, handle: any): void;
}
/**
* @en Class for TTFFont asset.
* @zh TTF 字体资源类。
*/
export class TTFFont extends Font {
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
_fontFamily: string | null;
constructor();
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
get _nativeAsset(): string | null;
set _nativeAsset(value: string | null);
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
get _nativeDep(): {
uuid: string;
__nativeName__: string;
ext: string;
__isNative__: boolean;
};
/**
* @en default init.
* @zh 默认初始化。
* @param uuid @en Asset uuid. @zh 资源 uuid。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
initDefault(uuid?: string): void;
}
/**
* @en Class for LabelAtlas handling.
* @zh 艺术数字字体资源类。
*
*/
export class LabelAtlas extends BitmapFont {
}
/**
* @en Class for BitmapFont handling.
* @zh 位图字体资源类。
*/
export class BitmapFont extends Font {
/**
* @deprecated since v3.7.0, Useless Code.
*/
fntDataStr: string;
/**
* @en [[SpriteFrame]] of the bitmap font.
* @zh 位图字体所使用的精灵。
*/
spriteFrame: SpriteFrame | null;
/**
* @en The font size.
* @zh 文字尺寸。
*/
fontSize: number;
/**
* @en Font configuration.
* @zh 字体配置。
*/
fntConfig: __private._cocos_2d_assets_bitmap_font__IConfig | null;
/**
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
fontDefDictionary: __private._cocos_2d_assets_bitmap_font__FontAtlas;
constructor();
onLoaded(): void;
}
/**
* @en Class for Font handling.
* @zh 字体资源类。
*/
export class Font extends Asset {
}
/**
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
export interface IUV {
u: number;
v: number;
}
/**
* @en Information object interface for initialize a [[SpriteFrame]] asset.
* @zh 用于初始化 [[SpriteFrame]] 资源的对象接口描述。
*/
export interface ISpriteFrameInitInfo {
/**
* @en The texture of the sprite frame, could be `TextureBase`.
* @zh 贴图对象资源，可以是 `TextureBase` 类型。
*/
texture?: __private._cocos_asset_assets_texture_base__TextureBase;
/**
* @en The original size of the sprite frame.
* @zh 精灵帧原始尺寸。
*/
originalSize?: math.Size;
/**
* @en The rect of the sprite frame in atlas texture.
* @zh 精灵帧裁切矩形。
*/
rect?: math.Rect;
/**
* @en The offset of the sprite frame center from the original center of the original rect.
* Sprite frame in an atlas texture could be trimmed for clipping the transparent pixels, so the trimmed rect is smaller than the original one,
* the offset defines the distance from the original center to the trimmed center.
* @zh 精灵帧偏移量。
* 在图集中的精灵帧可能会被剔除透明像素以获得更高的空间利用李，剔除后的矩形尺寸比剪裁前更小，偏移量指的是从原始矩形的中心到剪裁后的矩形中心的距离。
*/
offset?: math.Vec2;
/**
* @en Top side border for sliced 9 frame.
* @zh 九宫格精灵帧的上边界。
* @default 0
*/
borderTop?: number;
/**
* @en Bottom side border for sliced 9 frame.
* @zh 九宫格精灵帧的下边界。
* @default 0
*/
borderBottom?: number;
/**
* @en Left side border for sliced 9 frame.
* @zh 九宫格精灵帧的左边界。
* @default 0
*/
borderLeft?: number;
/**
* @en Right side border for sliced 9 frame.
* @zh 九宫格精灵帧的右边界。
* @default 0
*/
borderRight?: number;
/**
* @en Whether the content of sprite frame is rotated.
* @zh 是否旋转。
*/
isRotate?: boolean;
/**
* @en Whether the uv is flipped.
* @zh 是否转置 UV。
*/
isFlipUv?: boolean;
}
/**
* @en
* A `SpriteFrame` support several types.
* 1. Rectangle sprite frame
* 2. Sliced 9 sprite frame
* 3. Mesh sprite frame
* It mainly contains:<br/>
* - texture: A `TextureBase` that will be used by render process.<br/>
* - rectangle: A rectangle of the texture.
* - Sliced 9 border insets: The distance of each side from the internal rect to the sprite frame rect.
* - vertices: Vertex list for the mesh type sprite frame.
* - uv: The quad uv.
* - uvSliced: The sliced 9 uv.
*
* @zh
* 精灵帧资源。
* 一个 SpriteFrame 支持多种类型
* 1. 矩形精灵帧
* 2. 九宫格精灵帧
* 3. 网格精灵帧
* 它主要包含下列数据：<br/>
* - 纹理：会被渲染流程使用的 `TextureBase` 资源。<br/>
* - 矩形：在纹理中的矩形区域。
* - 九宫格信息：九宫格的内部矩形四个边距离 SpriteFrame 外部矩形的距离。
* - 网格信息：网格类型精灵帧的所有顶点列表。
* - uv: 四边形 UV。
* - uvSliced: 九宫格 UV。
* 可通过 `SpriteFrame` 获取该组件。
*
* @example
* ```ts
* import { resources } from 'cc';
* // First way to use a SpriteFrame
* const url = "assets/PurpleMonster/icon/spriteFrame";
* resources.load(url, (err, spriteFrame) => {
* const node = new Node("New Sprite");
* const sprite = node.addComponent(Sprite);
* sprite.spriteFrame = spriteFrame;
* node.parent = self.node;
* });
*
* // Second way to use a SpriteFrame
* const self = this;
* const url = "test_assets/PurpleMonster";
* resources.load(url, (err, imageAsset) => {
* if(err){
* return;
* }
*
* const node = new Node("New Sprite");
* const sprite = node.addComponent(Sprite);
* const spriteFrame = new SpriteFrame();
* const tex = imageAsset._texture;
* spriteFrame.texture = tex;
* sprite.spriteFrame = spriteFrame;
* node.parent = self.node;
* });
*
* // Third way to use a SpriteFrame
* const self = this;
* const cameraComp = this.getComponent(Camera);
* const renderTexture = new RenderTexture();
* renderTexture.reset({
* width: 512,
* height: 512,
* depthStencilFormat: RenderTexture.DepthStencilFormat.DEPTH_24_STENCIL_8
* });
*
* cameraComp.targetTexture = renderTexture;
* const spriteFrame = new SpriteFrame();
* spriteFrame.texture = renderTexture;
* ```
*/
export class SpriteFrame extends Asset {
/**
* @en Create a SpriteFrame object by an image asset or an native image asset.
* @zh 通过 Image 资源或者平台相关 Image 对象创建一个 SpriteFrame 资源。
* @param imageSourceOrImageAsset @en ImageAsset or ImageSource, ImageSource could be HTMLCanvasElement, HTMLImageElement, IMemoryImageSource.
* @zh 图像资源或图像原始图像源，图像原始图像源支持 HTMLCanvasElement HTMLImageElement IMemoryImageSource 三种资源。
* @returns @en SpriteFrame asset. @zh 精灵资源。
*/
static createWithImage(imageSourceOrImageAsset: __private._cocos_asset_assets_image_asset__ImageSource | ImageAsset): SpriteFrame;
/**
* @en uv update event.
* @zh uv 更新事件。
*/
static EVENT_UV_UPDATED: string;
static MeshType: typeof __private._cocos_2d_assets_sprite_frame__MeshType;
/**
* @en Top border distance of sliced 9 rect.
* @zh 九宫格内部矩形顶部边框距离 SpriteFrame 矩形的距离。
*/
get insetTop(): number;
set insetTop(value: number);
/**
* @en Bottom border distance of sliced 9 rect.
* @zh 九宫格内部矩形底部边框距离 SpriteFrame 矩形的距离。
*/
get insetBottom(): number;
set insetBottom(value: number);
/**
* @en Left border distance of sliced 9 rect.
* @zh 九宫格内部矩形左边框距离 SpriteFrame 矩形的距离。
*/
get insetLeft(): number;
set insetLeft(value: number);
/**
* @en Right border distance of sliced 9 rect.
* @zh 九宫格内部矩形右边框距离 SpriteFrame 矩形的距离。
*/
get insetRight(): number;
set insetRight(value: number);
/**
* @en Returns the rect of the sprite frame in the texture.
* If it's an atlas texture, a transparent pixel area is proposed for the actual mapping of the current texture.
* @zh 获取 SpriteFrame 的纹理矩形区域。
* 如果是一个 atlas 的贴图，则为当前贴图的实际剔除透明像素区域。
*/
get rect(): math.Rect;
set rect(value: math.Rect);
/**
* @en The original size before trimmed.
* @zh 修剪前的原始大小。
*/
get originalSize(): math.Size;
set originalSize(value: math.Size);
/**
* @en The offset of the sprite frame center.
* Sprite frame in an atlas texture could be trimmed for clipping the transparent pixels, so the trimmed rect is smaller than the original one,
* the offset defines the distance from the original center to the trimmed center.
* @zh 精灵帧偏移量。
* 在图集中的精灵帧可能会被剔除透明像素以获得更高的空间利用李，剔除后的矩形尺寸比剪裁前更小，偏移量指的是从原始矩形的中心到剪裁后的矩形中心的距离。
*/
get offset(): math.Vec2;
set offset(value: math.Vec2);
/**
* @en Whether the content of sprite frame is rotated.
* @zh 是否旋转。
*/
get rotated(): boolean;
set rotated(rotated: boolean);
/**
* @en The texture of the sprite frame, could be `TextureBase`.
* @zh 贴图对象资源，可以是 `TextureBase` 类型。
*/
get texture(): __private._cocos_asset_assets_texture_base__TextureBase;
set texture(value: __private._cocos_asset_assets_texture_base__TextureBase);
/**
* @en The uuid of the atlas asset, if exists.
* @zh 图集资源的 uuid。
*/
get atlasUuid(): string;
set atlasUuid(value: string);
/**
* @en The pixel width of the sprite frame.
* @zh 精灵帧的像素宽度。
*/
get width(): number;
/**
* @en The pixel height of the sprite frame.
* @zh 精灵帧的像素高度。
*/
get height(): number;
/**
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
set _textureSource(value: __private._cocos_asset_assets_texture_base__TextureBase);
/**
* @en Whether flip the uv in X direction.
* @zh 沿 X 轴方向, 翻转 UV。
*/
get flipUVX(): boolean;
set flipUVX(value: boolean);
/**
* @en Whether flip the uv in Y direction.
* @zh 沿 Y 轴方向, 翻转 UV。
*/
get flipUVY(): boolean;
set flipUVY(value: boolean);
/**
* @en Sets whether sprite can be packed into dynamic atlas.
* @zh 设置精灵是否允许参与自动合图。
*/
get packable(): boolean;
set packable(value: boolean);
/**
* @en Original information before packed to dynamic atlas, includes texture, width, height. It's null before being packed to dynamic atlas.
* @zh 精灵自动合图之前的原始 texture 和宽高信息。在参与自动合图之前此值为 null。
*/
get original(): {
_texture: __private._cocos_asset_assets_texture_base__TextureBase;
_x: number;
_y: number;
} | null;
/**
* @en Number of pixels corresponding to unit size in world space (pixels per unit).
* @zh 世界空间中的单位大小对应的像素数量（像素每单位）。
*/
get pixelsToUnit(): number;
/**
* @en Local origin position when generating the mesh.
* @zh 生成 mesh 时本地坐标原点位置。
*/
get pivot(): math.Vec2;
/**
* @en mesh information, you should call the [[ensureMeshData]] function before using it.
* @zh mesh 信息，你应该在使用它之前调用 [[ensureMeshData]] 函数来确保其可用。
*/
get mesh(): Mesh | null;
/**
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get trimmedBorder(): math.Vec4;
/**
* @en Vertex list for the mesh type sprite frame.
* @zh 网格类型精灵帧的所有顶点列表。
*/
vertices: __private._cocos_2d_assets_sprite_frame__IVertices | null;
/**
* @en UV for quad vertices.
* @zh 矩形的顶点 UV。
*/
uv: number[];
/**
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
unbiasUV: number[];
/**
* @en UV for sliced 9 vertices.
* @zh 九宫格的顶点 UV。
*/
uvSliced: IUV[];
protected _rect: math.Rect;
protected _trimmedBorder: math.Vec4;
protected _offset: math.Vec2;
protected _originalSize: math.Size;
protected _rotated: boolean;
protected _capInsets: number[];
protected _atlasUuid: string;
protected _texture: __private._cocos_asset_assets_texture_base__TextureBase;
protected _isFlipUVY: boolean;
protected _isFlipUVX: boolean;
protected _original: {
_texture: __private._cocos_asset_assets_texture_base__TextureBase;
_x: number;
_y: number;
} | null;
protected _packable: boolean;
protected _pixelsToUnit: number;
protected _pivot: math.Vec2;
protected _meshType: __private._cocos_2d_assets_sprite_frame__MeshType;
protected _extrude: number;
protected _customOutLine: never[];
protected _mesh: Mesh | null;
protected _minPos: math.Vec3;
protected _maxPos: math.Vec3;
constructor();
/**
* @en
* Returns whether the texture have been loaded.
* @zh
* 返回是否已加载精灵帧。
*
* @deprecated since v3.3, Useless Code.
*/
textureLoaded(): boolean;
/**
* @en
* Returns whether the sprite frame is rotated in the texture.
* @zh
* 获取 SpriteFrame 是否旋转。
* @deprecated since v1.2, please use [[rotated]] instead.
*/
isRotated(): boolean;
/**
* @en
* Set whether the sprite frame is rotated in the texture.
* @zh
* 设置 SpriteFrame 是否旋转。
* @param rotated @en rotated. @zh 是否旋转。
* @deprecated since v1.2, please use [[rotated]] instead.
*/
setRotated(rotated: boolean): void;
/**
* @en Returns the rect of the sprite frame in the texture.
* If it's an atlas texture, a transparent pixel area is proposed for the actual mapping of the current texture.
* @zh 获取 SpriteFrame 的纹理矩形区域。
* 如果是一个 atlas 的贴图，则为当前贴图的实际剔除透明像素区域。
* @param out @en The output rect. @zh 输出的矩形区域。
* @returns @en The rect. @zh 矩形区域。
* @deprecated since v1.2, please use [[rect]].
*/
getRect(out?: math.Rect): math.Rect;
/**
* @en Sets the rect of the sprite frame in the texture.
* @zh 设置 SpriteFrame 的纹理矩形区域。
* @param rect @en The new rect. @zh 想要设置的 rect。
* @deprecated since v1.2, please use [[rect]].
*/
setRect(rect: math.Rect): void;
/**
* @en Returns the original size before trimmed.
* @zh 获取修剪前的原始大小。
* @param out @en The output original size. @zh 输出的原始大小。
* @returns @en The original size. @zh 原始大小。
* @deprecated since v1.2, please use [[originalSize]].
*/
getOriginalSize(out?: math.Size): math.Size;
/**
* @en Sets the original size before trimmed.
* @zh 设置修剪前的原始大小。
* @param size @en The new original size. @zh 新设置的原始大小。
* @deprecated since v1.2, please use [[originalSize]].
*/
setOriginalSize(size: math.Size): void;
/**
* @en Gets the offset of the frame.
* @zh 获取偏移量。
* @param out @en The output offset object. @zh 输出的偏移量。
* @returns @en The offset object. @zh 偏移量。
* @deprecated since v1.2, please use [[offset]]
*/
getOffset(out?: math.Vec2): math.Vec2;
/**
* @en Sets the offset of the frame.
* @zh 设置偏移量。
* @param offset @en The new offset. @zh 新设置的偏移量。
* @deprecated since v1.2, please use [[offset]]
*/
setOffset(offset: math.Vec2): void;
/**
* @en Gets the related GFX [[gfx.Texture]] resource.
* @zh 获取渲染贴图的 GFX 资源。
* @returns @en Gfx Texture resource. @zh GFX 贴图资源。
*/
getGFXTexture(): gfx.Texture | null;
/**
* @en Gets the GFX sampler of its texture.
* @zh 贴图资源的采样器。
* @returns @en The GFX sampler resource. @zh GFX贴图采样器。
*/
getGFXSampler(): gfx.Sampler;
/**
* @en Gets the hash of its texture.
* @zh 贴图资源的哈希值。
* @returns @en Texture`s hash. @zh 贴图哈希值。
*/
getHash(): number;
/**
* @en Gets the sampler hash of its texture.
* @zh 贴图资源的采样器哈希值。
* @returns @en Sampler`s hash. @zh 采样器哈希值。
*/
getSamplerInfo(): Readonly<gfx.SamplerInfo>;
/**
* @en Resets the sprite frame data.
* @zh 重置 SpriteFrame 数据。
* @param info @en SpriteFrame initialization information. @zh SpriteFrame 初始化信息。
* @param clearData @en Clear Data before initialization. @zh 是否在初始化前清空原有数据。
*/
reset(info?: ISpriteFrameInitInfo, clearData?: boolean): void;
/**
* @en Check whether the rect of the sprite frame is out of the texture boundary.
* @zh 判断精灵计算的矩形区域是否越界。
* @param texture @en Texture resources for sprite frame. @zh SpriteFrame 的贴图资源。
* @returns @en Out of the texture boundary or not. @zh 矩形区域是否越界。
*/
checkRect(texture: __private._cocos_asset_assets_texture_base__TextureBase): boolean;
/**
* @en Make sure the mesh is available, you should call it before using the mesh.
* @zh 确保 mesh 可用，你应该在使用 mesh 之前调用它。
*/
ensureMeshData(): void;
destroy(): boolean;
/**
* Calculate UV for sliced
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
_calculateSlicedUV(): void;
/**
* Calculate UV
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
_calculateUV(): void;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
_setDynamicAtlasFrame(frame: any): void;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
_resetDynamicAtlasFrame(): void;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
_checkPackable(): void;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
_serialize(ctxForExporting: any): any;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
_deserialize(serializeData: any, handle: any): void;
/**
* @en clone a sprite frame.
* @zh 克隆当前 sprite frame。
*/
clone(): SpriteFrame;
protected _refreshTexture(texture: __private._cocos_asset_assets_texture_base__TextureBase): void;
/**
* @en complete loading callback.
* @zh 加载完成回调。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
onLoaded(): void;
/**
* @en default init.
* @zh 默认初始化。
* @param uuid @en Asset uuid. @zh 资源 uuid。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
initDefault(uuid?: string): void;
/**
* @en Check whether the sprite frame is validate.
* @zh 检查当前 sprite frame 对象是否是有效的。
* @returns @en validate or not. @zh 是否有效。
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
validate(): boolean;
protected _initVertices(): void;
protected _updateMeshVertices(): void;
protected _createMesh(): void;
protected _updateMesh(): void;
}
/**
* @en
* The root node of UI.
* Provide an aligned window for all child nodes, also provides ease of setting screen adaptation policy interfaces from the editor.
* Line-of-sight range is -999 to 1000.
*
* @zh
* 作为 UI 根节点，为所有子节点提供对齐视窗，另外提供屏幕适配策略接口，方便从编辑器设置。
* 注：由于本节点的尺寸会跟随屏幕拉伸，所以 anchorPoint 只支持 (0.5, 0.5)，否则适配不同屏幕时坐标会有偏差。
* UI 的视距范围是 -999 ～ 1000.
*/
export class Canvas extends RenderRoot2D {
/**
* @en
* The render mode of Canvas.
* When you choose the mode of INTERSPERSE, You can specify the rendering order of the Canvas with the camera in the scene.
* When you choose the mode of OVERLAY, the builtin camera of Canvas will render after all scene cameras are rendered.
* NOTE: The cameras in the scene (including the Canvas built-in camera) must have a ClearFlag selection of SOLID_COLOR,
* otherwise a splash screen may appear on the mobile device.
*
* @zh
* Canvas 渲染模式。
* intersperse 下可以指定 Canvas 与场景中的相机的渲染顺序，overlay 下 Canvas 会在所有场景相机渲染完成后渲染。
* 注意：场景里的相机（包括 Canvas 内置的相机）必须有一个的 ClearFlag 选择 SOLID_COLOR，否则在移动端可能会出现闪屏。
*
* @deprecated since v3.0, please use [[Camera.priority]] to control overlapping between cameras.
*/
get renderMode(): number;
set renderMode(val: number);
/**
* @en The camera component that will be aligned with this canvas
* @zh 将与此 canvas 对齐的相机组件
*/
get cameraComponent(): Camera | null;
set cameraComponent(value: Camera | null);
/**
* @en Align canvas with screen
* @zh 是否使用屏幕对齐画布
*/
get alignCanvasWithScreen(): boolean;
set alignCanvasWithScreen(value: boolean);
protected _cameraComponent: Camera | null;
protected _alignCanvasWithScreen: boolean;
protected _thisOnCameraResized: () => void;
protected fitDesignResolution_EDITOR: (() => void) | undefined;
constructor();
__preload(): void;
onEnable(): void;
onDisable(): void;
onDestroy(): void;
protected _onResizeCamera(): void;
}
/**
* @en Legacy 2D base class for rendering component, please use [[UI