declare module "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;
/**
* @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;
/**
* @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;
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:
* - texture: A `TextureBase` that will be used by render process.
* - 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. 网格精灵帧
* 它主要包含下列数据：
* - 纹理：会被渲染流程使用的 `TextureBase` 资源。
* - 矩形：在纹理中的矩形区域。
* - 九宫格信息：九宫格的内部矩形四个边距离 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;
/**
* @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 [[UIRenderer]] instead.
* This component will setup NodeUIProperties.uiComp in its owner [[Node]].
* @zh 旧的 2D 渲染组件基类，请使用 [[UIRenderer]] 替代。
* 这个组件会设置 [[Node]] 上的 NodeUIProperties.uiComp。
* @deprecated since v3.4.1, please use [[UIRenderer]] instead.
*/
export class UIComponent extends Component {
protected _lastParent: Node | null;
__preload(): void;
onEnable(): void;
onDisable(): void;
onDestroy(): void;
/**
* @en Post render data submission procedure, it's executed after assembler updated for all children.
* It may assemble some extra render data to the geometry buffers, or it may only change some render states.
* Don't call it unless you know what you are doing.
* @zh 后置渲染数据组装程序，它会在所有子节点的渲染数据组装完成后被调用。
* 它可能会组装额外的渲染数据到顶点数据缓冲区，也可能只是重置一些渲染状态。
* 注意：不要手动调用该函数，除非你理解整个流程。
* @deprecated since v3.4.1, please use [[UIRenderer]] instead.
*/
postUpdateAssembler(render: __private._cocos_2d_renderer_i_batcher__IBatcher): void;
/**
* @deprecated since v3.4.1, please use [[UIRenderer]] instead.
*/
markForUpdateRenderData(enable?: boolean): void;
/**
* @deprecated since v3.4.1, please use [[UIRenderer]] instead.
*/
stencilStage: __private._cocos_2d_renderer_stencil_manager__Stage;
/**
* @deprecated since v3.4.1, please use [[UIRenderer]] instead.
*/
setNodeDirty(): void;
/**
* @deprecated since v3.4.1, please use [[UIRenderer]] instead.
*/
setTextureDirty(): void;
}
/**
* @en
* The shader property type of the material after instantiation.
*
* @zh
* 实例后的材质的着色器属性类型。
*/
export enum InstanceMaterialType {
/**
* @en
* The shader only has color properties.
*
* @zh
* 着色器只带颜色属性。
*/
ADD_COLOR = 0,
/**
* @en
* The shader has color and texture properties.
*
* @zh
* 着色器带颜色和贴图属性。
*/
ADD_COLOR_AND_TEXTURE = 1,
/**
* @en
* The shader has color and texture properties and uses grayscale mode.
*
* @zh
* 着色器带颜色和贴图属性,并使用灰度模式。
*/
GRAYSCALE = 2,
/**
* @en
* The shader has color and texture properties and uses embedded alpha mode.
*
* @zh
* 着色器带颜色和贴图属性,并使用透明通道分离贴图。
*/
USE_ALPHA_SEPARATED = 3,
/**
* @en
* The shader has color and texture properties and uses embedded alpha and grayscale mode.
*
* @zh
* 着色器带颜色和贴图属性,并使用灰度模式。
*/
USE_ALPHA_SEPARATED_AND_GRAY = 4
}
/**
* @en Base class for UI components which supports rendering features.
* This component will setup NodeUIProperties.uiComp in its owner [[Node]]
*
* @zh 所有支持渲染的 UI 组件的基类。
* 这个组件会设置 [[Node]] 上的 NodeUIProperties.uiComp。
*/
export class UIRenderer extends Renderer {
/**
* @en The blend factor enums
* @zh 混合模式枚举类型
* @see [[gfx.BlendFactor]]
* @internal
*/
static BlendState: typeof gfx.BlendFactor;
/**
* @en The render data assembler
* @zh 渲染数据组装器
* @internal
*/
static Assembler: IAssemblerManager;
/**
* @en The post render data assembler
* @zh 后置渲染数据组装器
* @internal
*/
static PostAssembler: IAssemblerManager | null;
constructor();
get sharedMaterials(): (Material | null)[];
set sharedMaterials(val: (Material | null)[]);
/**
* @en The customMaterial
* @zh 用户自定材质
*/
get customMaterial(): Material | null;
set customMaterial(val: Material | null);
/**
* @en Main color for rendering, it normally multiplies with texture color.
* @zh 渲染颜色，一般情况下会和贴图颜色相乘。
*/
get color(): Readonly;
set color(value: Readonly);
protected _renderData: RenderData | null;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get renderData(): RenderData | null;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get useVertexOpacity(): boolean;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
* @en The component stencil stage (please do not any modification directly on this object)
* @zh 组件模板缓冲状态 (注意：请不要直接修改它的值)
*/
get stencilStage(): __private._cocos_2d_renderer_stencil_manager__Stage;
set stencilStage(val: __private._cocos_2d_renderer_stencil_manager__Stage);
protected _materials: (Material | null)[];
protected _customMaterial: Material | null;
protected _srcBlendFactor: gfx.BlendFactor;
protected _dstBlendFactor: gfx.BlendFactor;
protected _color: math.Color;
protected _stencilStage: __private._cocos_2d_renderer_stencil_manager__Stage;
protected _assembler: IAssembler | null;
protected _postAssembler: IAssembler | null;
protected _renderDataFlag: boolean;
protected _renderFlag: boolean;
protected _renderEntity: __private._cocos_2d_renderer_render_entity__RenderEntity;
protected _instanceMaterialType: number;
protected _srcBlendFactorCache: gfx.BlendFactor;
protected _dstBlendFactorCache: gfx.BlendFactor;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
_dirtyVersion: number;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
_internalId: number;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get batcher(): UI;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get renderEntity(): __private._cocos_2d_renderer_render_entity__RenderEntity;
/**
* @en Marks for calculating opacity per vertex
* @zh 标记组件是否逐顶点计算透明度
*/
protected _useVertexOpacity: boolean;
protected _lastParent: Node | null;
onLoad(): void;
__preload(): void;
onEnable(): void;
onRestore(): void;
onDisable(): void;
onDestroy(): void;
/**
* @en Marks the render data of the current component as modified so that the render data is recalculated.
* @zh 标记当前组件的渲染数据为已修改状态，这样渲染数据才会重新计算。
* @param enable Marked necessary to update or not
*/
markForUpdateRenderData(enable?: boolean): void;
/**
* @en Request new render data object.
* @zh 请求新的渲染数据对象。
* @return @en The new render data. @zh 新的渲染数据。
*/
requestRenderData(drawInfoType?: __private._cocos_2d_renderer_render_draw_info__RenderDrawInfoType): RenderData;
/**
* @en Destroy current render data.
* @zh 销毁当前渲染数据。
*/
destroyRenderData(): void;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
updateRenderer(): void;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
fillBuffers(render: __private._cocos_2d_renderer_i_batcher__IBatcher): void;
/**
* @en Post render data submission procedure, it's executed after assembler updated for all children.
* It may assemble some extra render data to the geometry buffers, or it may only change some render states.
* Don't call it unless you know what you are doing.
* @zh 后置渲染数据组装程序，它会在所有子节点的渲染数据组装完成后被调用。
* 它可能会组装额外的渲染数据到顶点数据缓冲区，也可能只是重置一些渲染状态。
* 注意：不要手动调用该函数，除非你理解整个流程。
*/
postUpdateAssembler(render: __private._cocos_2d_renderer_i_batcher__IBatcher): void;
protected _render(render: __private._cocos_2d_renderer_i_batcher__IBatcher): void;
protected _postRender(render: __private._cocos_2d_renderer_i_batcher__IBatcher): void;
protected _canRender(): boolean;
protected _postCanRender(): void;
protected _updateColor(): void;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
static setEntityColorDirtyRecursively(node: Node, dirty: boolean): void;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
setEntityColor(color: math.Color): void;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
setEntityOpacity(opacity: number): void;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
setEntityEnabled(enabled: boolean): void;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
_updateBlendFunc(): void;
protected _nodeStateChange(transformType: TransformBit): void;
protected _colorDirty(): void;
protected _onMaterialModified(idx: number, material: Material | null): void;
protected _updateBuiltinMaterial(): Material;
protected _flushAssembler?(): void;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
setNodeDirty(): void;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
setTextureDirty(): void;
protected createRenderEntity(): __private._cocos_2d_renderer_render_entity__RenderEntity;
}
/**
* @en
* The component of transform in UI.
*
* @zh
* UI 变换组件。
*/
export class UITransform extends Component {
/**
* @en
* Size of the UI node.
*
* @zh
* 内容尺寸。
*/
get contentSize(): Readonly;
set contentSize(value: Readonly);
/**
* @en
* component width.
* @zh
* 组件宽度。
*/
get width(): number;
set width(value: number);
/**
* @en
* component height.
* @zh
* 组件高度。
*/
get height(): number;
set height(value: number);
/**
* @en
* Anchor point of the UI node.
*
* @zh
* 锚点位置。
*/
get anchorPoint(): Readonly;
set anchorPoint(value: Readonly);
/**
* @en
* The x-axis anchor of the node.
*
* @zh
* 锚点位置的 X 坐标。
*/
get anchorX(): number;
set anchorX(value: number);
/**
* @en
* The y-axis anchor of the node.
*
* @zh
* 锚点位置的 Y 坐标。
*/
get anchorY(): number;
set anchorY(value: number);
/**
* @en
* Render sequence.
* Note: UI rendering is only about priority.
*
* @zh
* 渲染先后顺序，按照广度渲染排列，按同级节点下进行一次排列。
* @deprecated Since v3.1
*/
get priority(): number;
set priority(value: number);
protected _priority: number;
/**
* @en Get the visibility bit-mask of the rendering camera
* @zh 查找被渲染相机的可见性掩码。
* @deprecated since v3.0
*/
get visibility(): number;
/**
* @en Get the priority of the rendering camera
* @zh 查找被渲染相机的渲染优先级。
*/
get cameraPriority(): number;
static EventType: typeof NodeEventType;
protected _contentSize: math.Size;
protected _anchorPoint: math.Vec2;
__preload(): void;
onLoad(): void;
onEnable(): void;
onDisable(): void;
onDestroy(): void;
/**
* @en
* Sets the untransformed size of the ui transform.
* The contentSize remains the same no matter if the node is scaled or rotated.
* @zh
* 设置节点 UI Transform 的原始大小，不受该节点是否被缩放或者旋转的影响。
*
* @param size @en The size of the UI transform. @zh UI Transform 的 Size 大小。
* @example
* ```ts
* import { Size } from 'cc';
* node.setContentSize(new Size(100, 100));
* ```
*/
setContentSize(size: math.Size): void;
/**
* @en
* Sets the untransformed size of the ui transform.
* The contentSize remains the same no matter if the node is scaled or rotated.
* @zh
* 设置节点 UI Transform 的原始大小，不受该节点是否被缩放或者旋转的影响。
*
* @param width @en The width of the UI transform. @zh UI Transform 的宽。
* @param height @en The height of the UI transform. @zh UI Transform 的高。
* @example
* ```ts
* import { Size } from 'cc';
* node.setContentSize(100, 100);
* ```
*/
setContentSize(width: number, height: number): void;
/**
* @en
* Sets the anchor point in percent.
* anchor point is the point around which all transformations and positioning manipulations take place.
* It's like a pin in the node where it is "attached" to its parent.
* The anchorPoint is normalized, like a percentage. (0,0) means the bottom-left corner and (1,1) means the top-right corner.
* But you can use values higher than (1,1) and lower than (0,0) too.
* The default anchor point is (0.5,0.5), so it starts at the center of the node.
*
* @zh
* 设置锚点的百分比。
* 锚点应用于所有变换和坐标点的操作，它就像在节点上连接其父节点的大头针。
* 锚点是标准化的，就像百分比一样。(0，0) 表示左下角，(1，1) 表示右上角。
* 但是你可以使用比（1，1）更高的值或者比（0，0）更低的值。
* 默认的锚点是（0.5，0.5），因此它开始于节点的中心位置。
* 注意：Creator 中的锚点仅用于定位所在的节点，子节点的定位不受影响。
*
* @param point @en Node anchor point or node x-axis anchor.
* @zh 节点锚点或节点 x 轴锚。
* @param y @en The y-axis anchor of the node.
* @zh 节点 y 轴锚。
* @example
* ```ts
* import { Vec2 } from 'cc';
* node.setAnchorPoint(new Vec2(1, 1));
* node.setAnchorPoint(1, 1);
* ```
*/
setAnchorPoint(point: math.Vec2 | Readonly | number, y?: number): void;
/**
* @zh UI 空间中的点击测试。
* @en Hit test with point in UI Space.
*
* @param uiPoint point in UI Space.
* @deprecated since v3.5.0, please use `uiTransform.hitTest(screenPoint: Vec2)` instead.
*/
isHit(uiPoint: math.Vec2): boolean;
/**
* @zh 屏幕空间中的点击测试。
* @en Hit test with point in Screen Space.
*
* @param screenPoint @en point in Screen Space. @zh 屏幕坐标中的点。
*/
hitTest(screenPoint: math.Vec2, windowId?: number): boolean;
/**
* @en
* Converts a Point to node (local) space coordinates.
*
* @zh
* 将一个 UI 节点世界坐标系下点转换到另一个 UI 节点 (局部) 空间坐标系，这个坐标系以锚点为原点。
* 非 UI 节点转换到 UI 节点(局部) 空间坐标系，请走 Camera 的 `convertToUINode`。
*
* @param worldPoint @en Point in world space.
* @zh 世界坐标点。
* @param out @en Point in local space.
* @zh 转换后坐标。
* @returns @en Return the relative position to the target node.
* @zh 返回与目标节点的相对位置。
* @example
* ```ts
* const newVec3 = uiTransform.convertToNodeSpaceAR(cc.v3(100, 100, 0));
* ```
*/
convertToNodeSpaceAR(worldPoint: math.Vec3, out?: math.Vec3): math.Vec3;
/**
* @en
* Converts a Point in node coordinates to world space coordinates.
*
* @zh
* 将距当前节点坐标系下的一个点转换到世界坐标系。
*
* @param nodePoint @en Point in local space.
* @zh 节点坐标。
* @param out @en Point in world space.
* @zh 转换后坐标。
* @returns @en Returns the coordinates in the UI world coordinate system.
* @zh 返回 UI 世界坐标系。
* @example
* ```ts
* const newVec3 = uiTransform.convertToWorldSpaceAR(3(100, 100, 0));
* ```
*/
convertToWorldSpaceAR(nodePoint: math.Vec3, out?: math.Vec3): math.Vec3;
/**
* @en
* Returns an axis aligned bounding box of this node in local space coordinate.
* The returned box is relative only to its parent, and it doesn't contain any child nodes.
* The behavior is slightly different with [[getBoundingBoxToWorld]] and [[getBoundingBoxTo]].
*
* @zh
* 返回父节坐标系下的轴向对齐的包围盒。
* 返回的包围盒仅仅只包含当前节点的轴向对齐包围盒，不包含子节点。
* 这个 API 的行为和 [[getBoundingBoxToWorld]] 和 [[getBoundingBoxTo]] 略有不同。
*
* @returns @en An axis aligned bounding box of this node in local space coordinate. @zh 本地坐标系下的包围盒。
* @example
* ```ts
* const boundingBox = uiTransform.getBoundingBox();
* ```
*/
getBoundingBox(): math.Rect;
/**
* @en
* Returns an axis aligned bounding box of this node in world space coordinate.
* The bounding box contains self and active children's world bounding box, and it will eliminate all zero sized nodes.
* @zh
* 返回节点在世界坐标系下的对齐轴向的包围盒（AABB）。
* 该边框包含自身和已激活的子节点的世界边框，但会剔除所有零大小的节点。
* @returns @en An axis aligned bounding box of this node in world space coordinate. @zh 世界坐标系下包围盒。
* @example
* ```ts
* const newRect = uiTransform.getBoundingBoxToWorld();
* ```
*/
getBoundingBoxToWorld(): math.Rect;
/**
* @en
* Returns the minimum bounding box in the coordinate system of the target node.
* The result contains the current node and its child node tree, and it will eliminates all zero size nodes.
* E.g. passing an identical matrix will return the world bounding box of the current node tree.
* @zh
* 返回在目标节点坐标系下包含当前包围盒及其子节点包围盒的最小总包围盒，但会剔除所有零大小的节点。
* 如果传入单位矩阵，将得到世界坐标系下的包围盒。
*
* @param targetMat @en The target node's world matrix representing its coordinate system.
* @zh 表示目标节点坐标系的世界矩阵。
* @returns @en The minimum bounding box containing the current bounding box and its child nodes.
* @zh 包含当前节点包围盒及其子节点包围盒的最小包围盒。
*/
getBoundingBoxTo(targetMat: math.Mat4): math.Rect;
/**
* @en
* Compute the corresponding aabb in world space for raycast.
* @zh
* 计算出此 UI_2D 节点在世界空间下的 aabb 包围盒。
* @param out @en The out object of aabb bounding box of the node in world space. @zh 输出节点在世界空间下的 aabb 包围盒。
* @returns @en The aabb bounding box of the node in world space. @zh 节点在世界空间下的 aabb 包围盒。
*/
getComputeAABB(out?: geometry.AABB): geometry.AABB;
protected _selfBoundingBox(out: math.Rect): math.Rect;
protected _parentChanged(node: Node): void;
}
/**
* @en The entry node for 2D object data collection, all 2D rendering objects need to be rendered under the RenderRoot node.
* @zh 2D 对象数据收集的入口节点，所有的 2D渲染对象需在 RenderRoot 节点下才可以被渲染。
*/
export class RenderRoot2D extends Component {
onEnable(): void;
onDisable(): void;
onDestroy(): void;
}
/**
* @en 2D rendering component that provides the ability to render sprite in 3D space.
* @zh 2D 渲染基础组件，提供精灵渲染在 3D 空间中的能力。
*/
export class SpriteRenderer extends ModelRenderer {
/**
* @en The spriteFrame that the component should render.
* @zh 该组件应渲染的 spriteFrame。
*/
get spriteFrame(): SpriteFrame | null;
set spriteFrame(value: SpriteFrame | null);
/**
* @en Rendering model of the component.
* @zh 该组件的渲染模型。
*/
get model(): renderer.scene.Model | null;
protected _spriteFrame: SpriteFrame | null;
protected _mode: __private._cocos_2d_framework_sprite_renderer__SpriteMode;
protected _color: math.Color;
protected _flipX: boolean;
protected _flipY: boolean;
protected _size: math.Vec2;
onLoad(): void;
onRestore(): void;
onEnable(): void;
onDisable(): void;
onDestroy(): void;
protected _updateModels(): void;
protected _createModel(): void;
protected _updateModelParams(): void;
protected _getBuiltinMaterial(): Material;
protected _onMaterialModified(idx: number, material: Material | null): void;
protected _onUpdateLocalDescriptorSet(): void;
protected _attachToScene(): void;
}
/**
* @en
* The Mask Component.
*
* @zh
* 遮罩组件。
*/
export class Mask extends Component {
/**
* @en The type for mask.
*
* @zh 遮罩组件类型。
*/
static Type: typeof __private._cocos_2d_components_mask__MaskType;
/**
* @en
* The mask type.
*
* @zh
* 遮罩类型。
*/
get type(): __private._cocos_2d_components_mask__MaskType;
set type(value: __private._cocos_2d_components_mask__MaskType);
/**
* @en
* Reverse mask.
* @zh
* 反向遮罩。
*/
get inverted(): boolean;
set inverted(value: boolean);
/**
* @en
* The segments for ellipse mask.
*
* TODO: remove segments, not supported by graphics
* @zh
* 椭圆遮罩的曲线细分数。
*/
get segments(): number;
set segments(value: number);
/**
* @en
* The mask image.
*
* @zh
* 遮罩所需要的贴图。
* @deprecated since v3.6.1
*/
get spriteFrame(): SpriteFrame | null;
set spriteFrame(value: SpriteFrame | null);
/**
* @en
* The alpha threshold.(Not supported Canvas Mode)
* The content is drawn only where the stencil have pixel with alpha greater than the alphaThreshold.
* Should be a float between 0 and 1.
* This default to 0.1.
* When it's set to 1, the stencil will discard all pixels, nothing will be shown.
* @zh
* Alpha 阈值（不支持 Canvas 模式）
* 只有当模板的像素的 alpha 大于等于 alphaThreshold 时，才会绘制内容。
* 该数值 0 ~ 1 之间的浮点数，默认值为 0.1
* 当被设置为 1 时，会丢弃所有蒙版像素，所以不会显示任何内容
*/
get alphaThreshold(): number;
set alphaThreshold(value: number);
/**
* @en Rendering component for providing stencil buffer information.
* @zh 用于提供 stencil buffer 信息的渲染组件。
*/
get subComp(): Sprite | Graphics | null;
protected _type: __private._cocos_2d_components_mask__MaskType;
protected _inverted: boolean;
protected _segments: number;
protected _alphaThreshold: number;
protected _sprite: Sprite | null;
protected _graphics: Graphics | null;
protected _stencilStage: __private._cocos_2d_renderer_stencil_manager__Stage;
onLoad(): void;
onEnable(): void;
onRestore(): void;
onDisable(): void;
onDestroy(): void;
/**
* @en Hit test with point in World Space.
* @zh 世界空间中的点击测试。
* @param worldPt @en point in World Space. @zh 世界空间中的点击点。
*/
isHit(worldPt: math.Vec2): boolean;
protected _nodeStateChange(type: TransformBit): void;
protected _createSprite(): void;
protected _createGraphics(): void;
protected _updateGraphics(): void;
protected _enableRender(): void;
protected _disableRender(): void;
protected _removeMaskNode(): void;
/**
* @deprecated Since v3.6, Because mask changes the inheritance relationship,
* you can directly manipulate the rendering components under the same node to complete the operation
*/
get customMaterial(): Material | null;
set customMaterial(val: Material | null);
/**
* @deprecated Since v3.6, Because mask changes the inheritance relationship,
* you can directly manipulate the rendering components under the same node to complete the operation
*/
get color(): math.Color | null;
set color(value: math.Color | null);
/**
* @deprecated Since v3.6, Because mask changes the inheritance relationship,
* you can directly manipulate the rendering components under the same node to complete the operation
*/
markForUpdateRenderData(enable?: boolean): void;
/**
* @deprecated Since v3.6, Because mask changes the inheritance relationship,
* you can directly manipulate the rendering components under the same node to complete the operation
*/
requestRenderData(any: any): void;
/**
* @deprecated Since v3.6, Because mask changes the inheritance relationship,
* you can directly manipulate the rendering components under the same node to complete the operation
*/
destroyRenderData(): void;
/**
* @deprecated Since v3.6, Because mask changes the inheritance relationship,
* you can directly manipulate the rendering components under the same node to complete the operation
*/
updateRenderer(): void;
/**
* @deprecated Since v3.6, Because mask changes the inheritance relationship,
* you can directly manipulate the rendering components under the same node to complete the operation
*/
fillBuffers(render: any): void;
/**
* @deprecated Since v3.6, Because mask changes the inheritance relationship,
* you can directly manipulate the rendering components under the same node to complete the operation
*/
postUpdateAssembler(render: any): void;
/**
* @deprecated Since v3.6, Because mask changes the inheritance relationship,
* you can directly manipulate the rendering components under the same node to complete the operation
*/
setNodeDirty(): void;
/**
* @deprecated Since v3.6, Because mask changes the inheritance relationship,
* you can directly manipulate the rendering components under the same node to complete the operation
*/
setTextureDirty(): void;
/**
* @deprecated Since v3.6, Because mask changes the inheritance relationship,
* you can directly manipulate the rendering components under the same node to complete the operation
*/
get sharedMaterial(): Material | null;
/**
* @deprecated Since v3.6, Because mask changes the inheritance relationship,
* you can directly manipulate the rendering components under the same node to complete the operation
*/
get sharedMaterials(): (Material | null)[] | null;
set sharedMaterials(val: (Material | null)[] | null);
/**
* @deprecated Since v3.6, Because mask changes the inheritance relationship,
* you can directly manipulate the rendering components under the same node to complete the operation
*/
get material(): any;
set material(val: any);
/**
* @deprecated Since v3.6, Because mask changes the inheritance relationship,
* you can directly manipulate the rendering components under the same node to complete the operation
*/
get materials(): (any)[];
set materials(val: (any)[]);
/**
* @deprecated Since v3.6, Because mask changes the inheritance relationship,
* you can directly manipulate the rendering components under the same node to complete the operation
*/
getMaterial(idx: number): any;
/**
* @deprecated Since v3.6, Because mask changes the inheritance relationship,
* you can directly manipulate the rendering components under the same node to complete the operation
*/
setMaterial(material: Material | renderer.MaterialInstance | null, index: number): void;
/**
* @deprecated Since v3.6, Because mask changes the inheritance relationship,
* you can directly manipulate the rendering components under the same node to complete the operation
*/
getMaterialInstance(idx: number): any;
/**
* @deprecated Since v3.6, Because mask changes the inheritance relationship,
* you can directly manipulate the rendering components under the same node to complete the operation
*/
setMaterialInstance(matInst: Material | renderer.MaterialInstance | null, index: number): void;
/**
* @deprecated Since v3.6, Because mask changes the inheritance relationship,
* you can directly manipulate the rendering components under the same node to complete the operation
*/
getRenderMaterial(index: number): any;
}
/**
* @en
* The RichText Component.
*
* @zh
* 富文本组件。
*/
export class RichText extends Component {
/**
* @en
* Content string of RichText.
*
* @zh
* 富文本显示的文本内容。
*/
get string(): string;
set string(value: string);
/**
* @en
* Horizontal Alignment of each line in RichText.
*
* @zh
* 文本内容的水平对齐方式。
*/
get horizontalAlign(): HorizontalTextAlignment;
set horizontalAlign(value: HorizontalTextAlignment);
/**
* @en
* Vertical Alignment of each line in RichText.
*
* @zh
* 文本内容的竖直对齐方式。
*/
get verticalAlign(): VerticalTextAlignment;
set verticalAlign(value: VerticalTextAlignment);
/**
* @en
* Font size of RichText.
*
* @zh
* 富文本字体大小。
*/
get fontSize(): number;
set fontSize(value: number);
/**
* @en
* Font color of RichText. Works when the text content does not have a color parameter set. Transparency cascade is not supported.
*
* @zh
* 富文本默认文字颜色。在文本内容没有设置颜色参数时生效。暂不支持颜色级联。
*/
get fontColor(): math.Color;
set fontColor(value: math.Color);
/**
* @en
* Custom System font of RichText.
*
* @zh
* 富文本定制系统字体。
*/
get fontFamily(): string;
set fontFamily(value: string);
/**
* @en
* Custom System font of RichText.
*
* @zh
* 富文本定制字体。
*/
get font(): TTFFont | null;
set font(value: TTFFont | null);
/**
* @en
* Whether use system font name or not.
*
* @zh
* 是否使用系统字体。
*/
get useSystemFont(): boolean;
set useSystemFont(value: boolean);
/**
* @en
* The cache mode of label. This mode only supports system fonts.
*
* @zh
* 文本缓存模式, 该模式只支持系统字体。
*/
get cacheMode(): CacheMode;
set cacheMode(value: CacheMode);
/**
* @en
* The maximize width of the RichText.
*
* @zh
* 富文本的最大宽度。
*/
get maxWidth(): number;
set maxWidth(value: number);
/**
* @en
* Line Height of RichText.
*
* @zh
* 富文本行高。
*/
get lineHeight(): number;
set lineHeight(value: number);
/**
* @en
* The image atlas for the img tag. For each src value in the img tag, there should be a valid spriteFrame in the image atlas.
*
* @zh
* 对于 img 标签里面的 src 属性名称，都需要在 imageAtlas 里面找到一个有效的 spriteFrame，否则 img tag 会判定为无效。
*/
get imageAtlas(): SpriteAtlas | null;
set imageAtlas(value: SpriteAtlas | null);
/**
* @en
* Once checked, the RichText will block all input events (mouse and touch) within
* the bounding box of the node, preventing the input from penetrating into the underlying node.
*
* @zh
* 选中此选项后，RichText 将阻止节点边界框中的所有输入事件（鼠标和触摸），从而防止输入事件穿透到底层节点。
*/
get handleTouchEvent(): boolean;
set handleTouchEvent(value: boolean);
/**
* @en Enum for horizontal text alignment.
*
* @zh 文本横向对齐类型。
*/
static HorizontalAlign: typeof HorizontalTextAlignment;
/**
* @en Enum for vertical text alignment.
*
* @zh 文本垂直对齐类型。
*/
static VerticalAlign: typeof VerticalTextAlignment;
protected _lineHeight: number;
protected _string: string;
protected _horizontalAlign: HorizontalTextAlignment;
protected _verticalAlign: VerticalTextAlignment;
protected _fontSize: number;
protected _fontColor: math.Color;
protected _maxWidth: number;
protected _fontFamily: string;
protected _font: TTFFont | null;
protected _isSystemFontUsed: boolean;
protected _userDefinedFont: TTFFont | null;
protected _cacheMode: CacheMode;
protected _imageAtlas: SpriteAtlas | null;
protected _handleTouchEvent: boolean;
protected _textArray: IHtmlTextParserResultObj[];
protected _segments: __private._cocos_2d_components_rich_text__ISegment[];
protected _labelSegmentsCache: __private._cocos_2d_components_rich_text__ISegment[];
protected _linesWidth: number[];
protected _lineCount: number;
protected _labelWidth: number;
protected _labelHeight: number;
protected _layoutDirty: boolean;
protected _lineOffsetX: number;
protected _updateRichTextStatus: () => void;
protected _labelChildrenNum: number;
constructor();
onLoad(): void;
onEnable(): void;
onDisable(): void;
onRestore(): void;
onDestroy(): void;
protected _addEventListeners(): void;
protected _removeEventListeners(): void;
protected _updateLabelSegmentTextAttributes(): void;
protected _createFontLabel(str: string): __private._cocos_2d_components_rich_text__ISegment;
protected _createImage(spriteFrame: SpriteFrame): __private._cocos_2d_components_rich_text__ISegment;
protected _onTTFLoaded(): void;
protected _measureText(styleIndex: number, string?: string): number | ((s: string) => number);
protected _onTouchEnded(event: EventTouch): void;
protected _containsTouchLocation(label: __private._cocos_2d_components_rich_text__ISegment, point: math.Vec2): boolean;
protected _resetState(): void;
protected _activateChildren(active: any): void;
protected _addLabelSegment(stringToken: string, styleIndex: number): __private._cocos_2d_components_rich_text__ISegment;
protected _updateRichTextWithMaxWidth(labelString: string, labelWidth: number, styleIndex: number): void;
protected _isLastComponentCR(stringToken: any): boolean;
protected _updateLineInfo(): void;
protected _needsUpdateTextLayout(newTextArray: IHtmlTextParserResultObj[]): boolean;
protected _addRichTextImageElement(richTextElement: IHtmlTextParserResultObj): void;
protected _updateTextDefaultColor(): void;
protected _updateRichText(): void;
protected _getFirstWordLen(text: string, startIndex: number, textLen: number): number;
protected _updateRichTextPosition(): void;
protected _convertLiteralColorValue(color: string): math.Color;
protected _applyTextAttribute(labelSeg: __private._cocos_2d_components_rich_text__ISegment): void;
protected _applyLayer(): void;
protected _resetLabelState(label: Label): void;
}
/**
* @en
* Renders a sprite in the scene.
*
* @zh
* 渲染精灵组件。
*/
export class Sprite extends UIRenderer {
/**
* @en
* The sprite atlas where the sprite is.
*
* @zh
* 精灵的图集。
*/
get spriteAtlas(): SpriteAtlas | null;
set spriteAtlas(value: SpriteAtlas | null);
/**
* @en
* The sprite frame of the sprite.
*
* @zh
* 精灵的精灵帧。
*/
get spriteFrame(): SpriteFrame | null;
set spriteFrame(value: SpriteFrame | null);
/**
* @en
* The sprite render type.
*
* @zh
* 精灵渲染类型。
*
* @example
* ```ts
* import { Sprite } from 'cc';
* sprite.type = Sprite.Type.SIMPLE;
* ```
*/
get type(): __private._cocos_2d_components_sprite__SpriteType;
set type(value: __private._cocos_2d_components_sprite__SpriteType);
/**
* @en
* The fill type, This will only have any effect if the "type" is set to “Sprite.Type.FILLED”.
*
* @zh
* 精灵填充类型，仅渲染类型设置为 Sprite.Type.FILLED 时有效。
*
* @example
* ```ts
* import { Sprite } from 'cc';
* sprite.fillType = Sprite.FillType.HORIZONTAL;
* ```
*/
get fillType(): __private._cocos_2d_components_sprite__FillType;
set fillType(value: __private._cocos_2d_components_sprite__FillType);
/**
* @en
* The fill Center, This will only have any effect if the "type" is set to “Sprite.Type.FILLED”.
*
* @zh
* 填充中心点，仅渲染类型设置为 Sprite.Type.FILLED 时有效。
*
* @example
* ```ts
* import { Vec2 } from 'cc';
* sprite.fillCenter = new Vec2(0, 0);
* ```
*/
get fillCenter(): math.Vec2;
set fillCenter(value: math.Vec2);
/**
* @en
* The fill Start, This will only have any effect if the "type" is set to “Sprite.Type.FILLED”.
*
* @zh
* 填充起始点，仅渲染类型设置为 Sprite.Type.FILLED 时有效。
*
* @example
* ```ts
* // -1 To 1 between the numbers
* sprite.fillStart = 0.5;
* ```
*/
get fillStart(): number;
set fillStart(value: number);
/**
* @en
* The fill Range, This will only have any effect if the "type" is set to “Sprite.Type.FILLED”.
*
* @zh
* 填充范围，仅渲染类型设置为 Sprite.Type.FILLED 时有效。
*
* @example
* ```ts
* // -1 To 1 between the numbers
* sprite.fillRange = 1;
* ```
*/
get fillRange(): number;
set fillRange(value: number);
/**
* @en
* specify the frame is trimmed or not.
*
* @zh
* 是否使用裁剪模式。
*
* @example
* ```ts
* sprite.trim = true;
* ```
*/
get trim(): boolean;
set trim(value: boolean);
/**
* @en Grayscale mode.
* @zh 是否以灰度模式渲染。
*/
get grayscale(): boolean;
set grayscale(value: boolean);
/**
* @en
* Specify the size tracing mode.
*
* @zh
* 精灵尺寸调整模式。
*
* @example
* ```ts
* import { Sprite } from 'cc';
* sprite.sizeMode = Sprite.SizeMode.CUSTOM;
* ```
*/
get sizeMode(): __private._cocos_2d_components_sprite__SizeMode;
set sizeMode(value: __private._cocos_2d_components_sprite__SizeMode);
/**
* @en Enum for fill type.
* @zh 填充类型。
*/
static FillType: typeof __private._cocos_2d_components_sprite__FillType;
/**
* @en Enum for sprite type.
* @zh Sprite 类型。
*/
static Type: typeof __private._cocos_2d_components_sprite__SpriteType;
/**
* @en Sprite's size mode, including trimmed size, raw size, and none.
* @zh 精灵尺寸调整模式。
*/
static SizeMode: typeof __private._cocos_2d_components_sprite__SizeMode;
/**
* @en Event types for sprite.
* @zh sprite 的事件类型。
*/
static EventType: typeof __private._cocos_2d_components_sprite__EventType;
protected _spriteFrame: SpriteFrame | null;
protected _type: __private._cocos_2d_components_sprite__SpriteType;
protected _fillType: __private._cocos_2d_components_sprite__FillType;
protected _sizeMode: __private._cocos_2d_components_sprite__SizeMode;
protected _fillCenter: math.Vec2;
protected _fillStart: number;
protected _fillRange: number;
protected _isTrimmedMode: boolean;
protected _useGrayscale: boolean;
protected _atlas: SpriteAtlas | null;
__preload(): void;
onEnable(): void;
onDisable(): void;
onDestroy(): void;
/**
* @en
* Quickly switch to other sprite frame in the sprite atlas.
* If there is no atlas, the switch fails.
*
* @zh
* 选取使用精灵图集中的其他精灵。
* @param name @en Name of the spriteFrame to switch. @zh 要切换的 spriteFrame 名字。
*/
changeSpriteFrameFromAtlas(name: string): void;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
changeMaterialForDefine(): void;
protected _updateBuiltinMaterial(): Material;
protected _render(render: __private._cocos_2d_renderer_i_batcher__IBatcher): void;
protected _canRender(): boolean;
protected _flushAssembler(): void;
public loadSpriteFrame(bundleName: string, path: string): void;
}
/**
* @en
* The component of model.
* When you place particles or models in the UI, you must add this component to render.
* The component must be placed on a node with the [[MeshRenderer]] or the [[ParticleSystem]].
*
* @zh
* UI 模型基础组件。
* 当你在 UI 中放置模型或者粒子的时候，必须添加该组件才能渲染。该组件必须放置在带有 [[MeshRenderer]] 或者 [[ParticleSystem]] 组件的节点上。
* @deprecated This component is not recommended to be used, please use Render Texture instead.
* See [UIMeshRenderer Reference](https://docs.cocos.com/creator/manual/en/ui-system/components/editor/ui-model.html)
*/
export class UIMeshRenderer extends Component {
constructor();
/**
* @en Get the model component on this node
* @zh 获取同节点的 model 组件
*/
get modelComponent(): ModelRenderer | null;
protected _renderEntity: __private._cocos_2d_renderer_render_entity__RenderEntity;
_dirtyVersion: number;
_internalId: number;
__preload(): void;
onEnable(): void;
onDisable(): void;
onLoad(): void;
onDestroy(): void;
/**
* @en Render data submission procedure, it update and assemble the render data to 2D data buffers before all children submission process.
* Usually called each frame when the ui flow assemble all render data to geometry buffers.
* Don't call it unless you know what you are doing.
* @zh 渲染数据组装程序，这个方法会在所有子节点数据组装之前更新并组装当前组件的渲染数据到 UI 的顶点数据缓冲区中。
* 一般在 UI 渲染流程中调用，用于组装所有的渲染数据到顶点数据缓冲区。
* 注意：不要手动调用该函数，除非你理解整个流程。
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
_render(render: __private._cocos_2d_renderer_i_batcher__IBatcher): boolean;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
fillBuffers(render: __private._cocos_2d_renderer_i_batcher__IBatcher): void;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
updateRenderer(): void;
/**
* @en Post render data submission procedure, it's executed after assembler updated for all children.
* It may assemble some extra render data to the geometry buffers, or it may only change some render states.
* Don't call it unless you know what you are doing.
* @zh 后置渲染数据组装程序，它会在所有子节点的渲染数据组装完成后被调用。
* 它可能会组装额外的渲染数据到顶点数据缓冲区，也可能只是重置一些渲染状态。
* 注意：不要手动调用该函数，除非你理解整个流程。
*/
postUpdateAssembler(render: __private._cocos_2d_renderer_i_batcher__IBatcher): void;
update(): void;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
markForUpdateRenderData(enable?: boolean): void;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
stencilStage: __private._cocos_2d_renderer_stencil_manager__Stage;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
setNodeDirty(): void;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
setTextureDirty(): void;
protected _canRender(): boolean;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get renderEntity(): __private._cocos_2d_renderer_render_entity__RenderEntity;
protected _renderData: RenderData | null;
/**
* @deprecated Since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get renderData(): RenderData | null;
}
/**
* @en
* Outline effect used to change the display, only for system fonts or TTF fonts.
*
* @zh
* 描边效果组件,用于字体描边,只能用于系统字体。
*
* @deprecated since v3.8.2, please use [[Label.enableOutline]] instead.
*/
export class LabelOutline extends Component {
/**
* @en
* Outline color.
*
* @zh
* 改变描边的颜色。
*
* @deprecated since v3.8.2, please use [[Label.outlineColor]] instead.
*/
get color(): Readonly;
set color(value: Readonly);
/**
* @en
* Change the outline width.
*
* @zh
* 改变描边的宽度。
*
* @deprecated since v3.8.2, please use [[Label.outlineWidth]] instead.
*/
get width(): number;
set width(value: number);
/**
* @deprecated since v3.8.2, please use [[Label.enableOutline]] instead.
*/
onEnable(): void;
/**
* @deprecated since v3.8.2, please use [[Label.enableOutline]] instead.
*/
onDisable(): void;
}
/**
* @en
* Graphics component.
*
* @zh
* 自定义图形类。
*/
export class Graphics extends UIRenderer {
/**
* @en
* Current line width.
*
* @zh
* 当前线条宽度。
*/
get lineWidth(): number;
set lineWidth(value: number);
/**
* @en
* Determines how two connecting segments (of lines, arcs or curves) with non-zero lengths in a shape are joined together.
*
* @zh
* 用来设置2个长度不为0的相连部分（线段，圆弧，曲线）如何连接在一起的属性。
*/
get lineJoin(): __private._cocos_2d_assembler_graphics_types__LineJoin;
set lineJoin(value: __private._cocos_2d_assembler_graphics_types__LineJoin);
/**
* @en
* Determines how the end points of every line are drawn.
*
* @zh
* 指定如何绘制每一条线段末端。
*/
get lineCap(): __private._cocos_2d_assembler_graphics_types__LineCap;
set lineCap(value: __private._cocos_2d_assembler_graphics_types__LineCap);
/**
* @en
* Brush stroke color.
*
* @zh
* 笔触的颜色。
*/
get strokeColor(): Readonly;
set strokeColor(value: Readonly);
/**
* @en
* Fill paint color.
*
* @zh
* 填充绘画的颜色。
*/
get fillColor(): Readonly;
set fillColor(value: Readonly);
/**
* @en
* Set the miter limit ratio.
*
* @zh
* 设置斜接面限制比例。
*/
get miterLimit(): number;
set miterLimit(value: number);
get color(): math.Color;
set color(value: math.Color);
static LineJoin: typeof __private._cocos_2d_assembler_graphics_types__LineJoin;
static LineCap: typeof __private._cocos_2d_assembler_graphics_types__LineCap;
impl: __private._cocos_2d_assembler_graphics_webgl_impl__Impl | null;
/**
* @deprecated since v3.6.0, this is an engine private interface that will be removed in the future.
*/
model: renderer.scene.Model | null;
protected _lineWidth: number;
protected _strokeColor: math.Color;
protected _lineJoin: __private._cocos_2d_assembler_graphics_types__LineJoin;
protected _lineCap: __private._cocos_2d_assembler_graphics_types__LineCap;
protected _fillColor: math.Color;
protected _miterLimit: number;
protected _isDrawing: boolean;
protected _isNeedUploadData: boolean;
protected _graphicsNativeProxy: __private._cocos_2d_renderer_native_2d__NativeUIModelProxy;
/**
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get graphicsNativeProxy(): __private._cocos_2d_renderer_native_2d__NativeUIModelProxy;
constructor();
onRestore(): void;
onLoad(): void;
onEnable(): void;
onDestroy(): void;
/**
* @en
* Move path start point to (x,y).
*
* @zh
* 移动路径起点到坐标(x, y)。
*
* @param x @en The x-axis coordinate of the target position.
* @zh 目标位置的 X 轴坐标。
* @param y @en The y-axis coordinate of the target position.
* @zh 目标位置的 y 轴坐标。
*/
moveTo(x: number, y: number): void;
/**
* @en
* Adds a straight line to the path.
*
* @zh
* 绘制直线路径。
*
* @param x @en The x-axis coordinate of the target position.
* @zh 目标位置的 x 轴坐标。
* @param y @en The x-axis coordinate of the target position.
* @zh 目标位置的 y 轴坐标。
*/
lineTo(x: number, y: number): void;
/**
* @en
* Adds a cubic Bézier curve to the path.
*
* @zh
* 绘制三次贝赛尔曲线路径。
*
* @param c1x @en The x-axis coordinate of the first control point.
* @zh 第一个控制点的 x 轴坐标。
* @param c1y @en The y-axis coordinate of the first control point.
* @zh 第一个控制点的 y 轴坐标。
* @param c2x @en The x-axis coordinate of the second control point.
* @zh 第二个控制点的 x 轴坐标。
* @param c2y @en The y-axis coordinate of the second control point.
* @zh 第二个控制点的 y 轴坐标。
* @param x @en The x-axis coordinate of the last control point.
* @zh 最后一个控制点的 x 轴坐标。
* @param y @en The y-axis coordinate of the last control point.
* @zh 最后一个控制点的 y 轴坐标。
*/
bezierCurveTo(c1x: number, c1y: number, c2x: number, c2y: number, x: number, y: number): void;
/**
* @en
* Adds a quadratic Bézier curve to the path.
*
* @zh
* 绘制二次贝赛尔曲线路径。
*
* @param cx @en The x-axis coordinate of the starting control point.
* @zh 起始控制点的 x 轴坐标。
* @param cy @en The y-axis coordinate of the starting control point.
* @zh 起始控制点的 y 轴坐标。
* @param x @en The x-axis coordinates of the endpoint control point.
* @zh 终点控制点的 x 轴坐标。
* @param y @en The y-axis coordinates of the endpoint control point.
* @zh 终点控制点的 x 轴坐标。
*/
quadraticCurveTo(cx: number, cy: number, x: number, y: number): void;
/**
* @en
* Adds an arc to the path which is centered at (cx, cy) position with radius r starting at startAngle
* and ending at endAngle going in the given direction by counterclockwise (defaulting to false).
*
* @zh
* 绘制圆弧路径。圆弧路径的圆心在 (cx, cy) 位置，半径为 r ，根据 counterclockwise （默认为false）指定的方向从 startAngle 开始绘制，到 endAngle 结束。
*
* @param cx @en The coordinate x-axis of the central control point.
* @zh 中心控制点的坐标 x 轴。
* @param cy @en The coordinate y-axis of the central control point.
* @zh 中心控制点的坐标 y 轴。
* @param r @en Angle in Radian.
* @zh 圆弧弧度。
* @param startAngle @en The starting angle in radian, measured clockwise from the positive x-axis.
* @zh 弧度起点，从正 x 轴顺时针方向测量。
* @param endAngle @en The ending angle in radian, measured clockwise from the positive x-axis.
* @zh 弧度终点，从正 x 轴顺时针方向测量。
* @param counterclockwise @en If true, draws counterclockwise between the two angles. Default is clockwise.
* @zh 如果为真，在两个角度之间逆时针绘制。默认顺时针。
*/
arc(cx: number, cy: number, r: number, startAngle: number, endAngle: number, counterclockwise: boolean): void;
/**
* @en
* Adds an ellipse to the path.
*
* @zh
* 绘制椭圆路径。
*
* @param cx @en The x-axis coordinates of the center point.
* @zh 中心点的 x 轴坐标。
* @param cy @en The y-axis coordinates of the center point.
* @zh 中心点的 y 轴坐标。
* @param rx @en The radius of the x-axis of the ellipse.
* @zh 椭圆 x 轴半径。
* @param ry @en The radius of the y-axis of the ellipse.
* @zh 椭圆 y 轴半径。
*/
ellipse(cx: number, cy: number, rx: number, ry: number): void;
/**
* @en
* Adds a circle to the path.
*
* @zh
* 绘制圆形路径。
*
* @param cx @en The x-axis coordinates of the center point.
* @zh 中心点的 x 轴坐标。
* @param cy @en The y-axis coordinates of the center point.
* @zh 中心点的 y 轴坐标。
* @param r @en Radius.
* @zh 圆半径。
*/
circle(cx: number, cy: number, r: number): void;
/**
* @en
* Adds a rectangle to the path.
*
* @zh
* 绘制矩形路径。
*
* @param x @en The x-axis coordinate of the top left point of the rectangle.
* @zh 矩形起始 x 轴坐标。
* @param y @en The y-axis coordinate of the top left point of the rectangle.
* @zh 矩形起始 y 轴坐标。
* @param w @en The width of the rectangle.
* @zh 矩形宽度。
* @param h @en The height of the rectangle.
* @zh 矩形高度。
*/
rect(x: number, y: number, w: number, h: number): void;
/**
* @en
* Adds a round corner rectangle to the path.
*
* @zh
* 绘制圆角矩形路径。
*
* @param x @en The x-axis coordinate of the top left point of the rectangle.
* @zh 矩形起始 x 轴坐标。
* @param y @en The y-axis coordinate of the top left point of the rectangle.
* @zh 矩形起始 y 轴坐标。
* @param w @en The width of the rectangle.
* @zh 矩形宽度。
* @param h @en The height of the rectangle.
* @zh 矩形高度。
* @param r @en Radius of rectangular rounded corners.
* @zh 矩形圆角半径。
*/
roundRect(x: number, y: number, w: number, h: number, r: number): void;
/**
* @en
* Draws a filled rectangle.
*
* @zh
* 绘制填充矩形。
*
* @param x @en The x-axis coordinate of the top left point of the rectangle.
* @zh 矩形起始 x 轴坐标。
* @param y @en The y-axis coordinate of the top left point of the rectangle.
* @zh 矩形起始 y 轴坐标。
* @param w @en The width of the rectangle.
* @zh 矩形宽度。
* @param h @en The height of the rectangle.
* @zh 矩形高度。
*/
fillRect(x: number, y: number, w: number, h: number): void;
/**
* @en
* Erasing any previously drawn content.
*
* @zh
* 擦除之前绘制的所有内容的方法。
*/
clear(): void;
/**
* @en
* Causes the point of the pen to move back to the start of the current path.
* It tries to add a straight line from the current point to the start.
*
* @zh
* 将笔点返回到当前路径起始点的。它尝试从当前点到起始点绘制一条直线。
*/
close(): void;
/**
* @en
* Strokes the current or given path with the current stroke style.
*
* @zh
* 根据当前的画线样式，绘制当前或已经存在的路径。
*/
stroke(): void;
/**
* @en
* Fills the current or given path with the current fill style.
*
* @zh
* 根据当前的画线样式，填充当前或已经存在的路径。
*/
fill(): void;
/**
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
activeSubModel(idx: number): void;
protected _uploadData(): void;
protected _render(render: __private._cocos_2d_renderer_i_batcher__IBatcher): void;
protected _flushAssembler(): void;
protected _canRender(): boolean;
/**
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
updateRenderer(): void;
protected createRenderEntity(): __private._cocos_2d_renderer_render_entity__RenderEntity;
}
/**
* @en
* Static batch component of UI.
* This component is placed on the root node of all node objects that need to be batch.
* Only sprites and label participate in the batch.
* Static batch must be enabled manually, otherwise dynamic batch is still used.
* Note: Do not place mask, Graphics, and objects such as UI models or particles under child nodes,
* otherwise rendering will be skipped after static batching is enabled.
*
* @zh
* UI 静态合批组件。
* 该组件放在所有需要被静态合批的节点对象的根节点上，子节点放置对象必须是精灵和文本，其余对象不参与静态合批。
* 用户必须通过手动方式启用收集静态合批数据[[markAsDirty]]，否则合批方式仍然采用动态合批（采集数据的流程相同）。此后渲染的内容是采用收集到的合批渲染数据，子节点的任何修改将不再有效。
* 注意：子节点下不要放置 Mask，Graphics，以及 UI 模型或者粒子之类对象，否则会在启用完静态合批后跳过渲染。
*
* @deprecated Since v3.4.1, We have adopted a new rendering batching policy in v3.4.1,
* which will result in an effective performance improvement for normal dynamic batching components,
* so manual management with the UIStaticBatch component is no longer recommended and will be removed in the future
*/
export class UIStaticBatch extends UIRenderer {
get color(): Readonly;
set color(value: Readonly);
get drawBatchList(): __private._cocos_2d_renderer_draw_batch__DrawBatch2D[];
protected _init: boolean;
protected _bufferAccessor: __private._cocos_2d_renderer_static_vb_accessor__StaticVBAccessor | null;
protected _dirty: boolean;
postUpdateAssembler(render: __private._cocos_2d_renderer_i_batcher__IBatcher): void;
/**
* @en
* Recollect data tags.
* The render data will be recollected during the render phase of the current frame, and the next frame will be rendered using fixed data.
* Note: 尽量不要频繁调用此接口, 会有一定内存损耗.
*
* @zh
* 重新采集数据标记，会在当前帧的渲染阶段重新采集渲染数据，下一帧开始将会使用固定数据进行渲染。
* 注意：尽量不要频繁调用此接口，因为会清空原先存储的 ia 数据重新采集，会有一定内存损耗。
*/
markAsDirty(): void;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
_requireDrawBatch(): __private._cocos_2d_renderer_draw_batch__DrawBatch2D;
protected _clearData(): void;
protected _getBatcher(): UI | null;
}
/**
* @en Shadow effect for Label component, only for system fonts or TTF fonts.
* @zh 用于给 Label 组件添加阴影效果，只能用于系统字体或 ttf 字体。
*
* @deprecated since v3.8.2, please use [[Label.enableShadow]] instead.
*/
export class LabelShadow extends Component {
/**
* @en
* Shadow color.
*
* @zh
* 阴影的颜色。
*
* @deprecated since v3.8.2, please use [[Label.shadowColor]] instead.
*/
get color(): Readonly;
set color(value: Readonly);
/**
* @en
* Offset between font and shadow.
*
* @zh
* 字体与阴影的偏移。
*
* @deprecated since v3.8.2, please use [[Label.shadowOffset]] instead.
*/
get offset(): math.Vec2;
set offset(value: math.Vec2);
/**
* @en
* A non-negative float specifying the level of shadow blur.
*
* @zh
* 阴影的模糊程度。
*
* @deprecated since v3.8.2, please use [[Label.shadowBlur]] instead.
*/
get blur(): number;
set blur(value: number);
/**
* @deprecated since v3.8.2, please use [[Label.enableShadow]] instead.
*/
onEnable(): void;
/**
* @deprecated since v3.8.2, please use [[Label.enableShadow]] instead.
*/
onDisable(): void;
}
/**
* @en
* Set the UI transparency component.
* This component can be used to influence subsequent render nodes.
* Nodes that already have a rendering component can modify the alpha channel of color directly.
*
* @zh
* UI 透明度设置组件。可以通过该组件设置透明度来影响后续的渲染节点。已经带有渲染组件的节点可以直接修改 color 的 alpha 通道。
*/
export class UIOpacity extends Component {
/**
* @en
* The transparency value of the impact.
*
* @zh
* 透明度。
*/
get opacity(): number;
set opacity(value: number);
static setEntityLocalOpacityDirtyRecursively(node: Node, dirty: boolean, interruptParentOpacity: number, setByParent: boolean): void;
protected _opacity: number;
onEnable(): void;
onDisable(): void;
}
/**
* @en Enum for horizontal text alignment.
*
* @zh 文本横向对齐类型。
*/
export enum HorizontalTextAlignment {
/**
* @en Alignment left for text.
*
* @zh 左对齐。
*/
LEFT = 0,
/**
* @en Alignment center for text.
*
* @zh 中心对齐。
*/
CENTER = 1,
/**
* @en Alignment right for text.
*
* @zh 右对齐。
*/
RIGHT = 2
}
/**
* @en Enum for vertical text alignment.
*
* @zh 文本垂直对齐类型。
*/
export enum VerticalTextAlignment {
/**
* @en Alignment top for text.
*
* @zh 上对齐。
*/
TOP = 0,
/**
* @en Alignment center for text.
*
* @zh 中心对齐。
*/
CENTER = 1,
/**
* @en Alignment bottom for text.
*
* @zh 下对齐。
*/
BOTTOM = 2
}
/**
* @en Enum for Overflow.
*
* @zh 文本溢出行为类型。
*/
export enum Overflow {
/**
* @en None.
*
* @zh 不做任何限制。
*/
NONE = 0,
/**
* @en In CLAMP mode, when label content goes out of the bounding box, it will be clipped.
*
* @zh CLAMP 模式中，当文本内容超出边界框时，多余的会被截断。
*/
CLAMP = 1,
/**
* @en In SHRINK mode, the font size will change dynamically to adapt the content size.
* This mode may takes up more CPU resources when the label is refreshed.
*
* @zh SHRINK 模式，字体大小会动态变化，以适应内容大小。这个模式在文本刷新的时候可能会占用较多 CPU 资源。
*/
SHRINK = 2,
/**
* @en In RESIZE_HEIGHT mode, you can only change the width of label and the height is changed automatically.
*
* @zh 在 RESIZE_HEIGHT 模式下，只能更改文本的宽度，高度是自动改变的。
*/
RESIZE_HEIGHT = 3
}
/**
* @en Enum for cache mode.
*
* @zh 文本图集缓存类型。
*/
export enum CacheMode {
/**
* @en Do not do any caching.
*
* @zh 不做任何缓存。
*/
NONE = 0,
/**
* @en In BITMAP mode, cache the label as a static image and add it to the dynamic atlas for batch rendering,
* and can batching with Sprites using broken images.
*
* @zh BITMAP 模式，将 label 缓存成静态图像并加入到动态图集，以便进行批次合并，可与使用碎图的 Sprite 进行合批。
* （注：动态图集在 Chrome 以及微信小游戏暂时关闭，该功能无效）。
*/
BITMAP = 1,
/**
* @en In CHAR mode, split text into characters and cache characters into a dynamic atlas which the size of 1024 * 1024.
*
* @zh CHAR 模式，将文本拆分为字符，并将字符缓存到一张单独的大小为 1024 * 1024 的图集中进行重复使用，不再使用动态图集。
* （注：当图集满时将不再进行缓存，暂时不支持 SHRINK 自适应文本尺寸（后续完善））。
*/
CHAR = 2
}
/**
* @en
* The Label Component.
*
* @zh
* 文字标签组件。
*/
export class Label extends UIRenderer {
/**
* @en Enum for horizontal text alignment.
*
* @zh 文本横向对齐类型。
*/
static HorizontalAlign: typeof HorizontalTextAlignment;
/**
* @en Enum for vertical text alignment.
*
* @zh 文本垂直对齐类型。
*/
static VerticalAlign: typeof VerticalTextAlignment;
/**
* @en Enum for label overflow mode.
*
* @zh 文本溢出行为类型。
*/
static Overflow: typeof Overflow;
/**
* @en Enum for cache mode.
*
* @zh 文本图集缓存类型。
*/
static CacheMode: typeof CacheMode;
/**
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
static _canvasPool: __private._cocos_2d_assembler_label_font_utils__CanvasPool;
/**
* @en
* Content string of label.
*
* @zh
* 标签显示的文本内容。
*/
get string(): string;
set string(value: string);
/**
* @en
* Horizontal Alignment of label.
*
* @zh
* 文本内容的水平对齐方式。
*/
get horizontalAlign(): HorizontalTextAlignment;
set horizontalAlign(value: HorizontalTextAlignment);
/**
* @en
* Vertical Alignment of label.
*
* @zh
* 文本内容的垂直对齐方式。
*/
get verticalAlign(): VerticalTextAlignment;
set verticalAlign(value: VerticalTextAlignment);
/**
* @en
* The actual rendering font size in shrink mode.
*
* @zh
* SHRINK 模式下面文本实际渲染的字体大小。
*/
get actualFontSize(): number;
set actualFontSize(value: number);
/**
* @en
* Font size of label.
*
* @zh
* 文本字体大小。
*/
get fontSize(): number;
set fontSize(value: number);
/**
* @en
* Line Height of label.
*
* @zh
* 文本行高。
*/
get lineHeight(): number;
set lineHeight(value: number);
/**
* @en
* The spacing between text characters, only available in BMFont.
*
* @zh
* 文本字符之间的间距。仅在使用 BMFont 位图字体时生效。
*/
get spacingX(): number;
set spacingX(value: number);
/**
* @en
* Overflow of label.
*
* @zh
* 文字显示超出范围时的处理方式。
*/
get overflow(): Overflow;
set overflow(value: Overflow);
/**
* @en
* Whether auto wrap label when string width is large than label width.
*
* @zh
* 是否自动换行。
*/
get enableWrapText(): boolean;
set enableWrapText(value: boolean);
/**
* @en
* Whether use system font name or not.
*
* @zh
* 是否使用系统字体。
*/
get useSystemFont(): boolean;
set useSystemFont(value: boolean);
/**
* @en
* Font family of label, only take effect when useSystemFont property is true.
*
* @zh
* 文本字体名称, 只在 useSystemFont 属性为 true 的时候生效。
*/
get fontFamily(): string;
set fontFamily(value: string);
/**
* @en
* The font of label.
*
* @zh
* 文本字体。
*/
get font(): Font | null;
set font(value: Font | null);
/**
* @en
* The cache mode of label. This mode only supports system fonts.
*
* @zh
* 文本缓存模式, 该模式只支持系统字体。
*/
get cacheMode(): CacheMode;
set cacheMode(value: CacheMode);
/**
* @en
* Whether the font is bold.
*
* @zh
* 字体是否加粗。
*/
get isBold(): boolean;
set isBold(value: boolean);
/**
* @en
* Whether the font is italic.
*
* @zh
* 字体是否倾斜。
*/
get isItalic(): boolean;
set isItalic(value: boolean);
/**
* @en
* Whether the font is underline.
*
* @zh
* 字体是否加下划线。
*/
get isUnderline(): boolean;
set isUnderline(value: boolean);
/**
* @en The height of underline.
* @zh 下划线高度。
*/
get underlineHeight(): number;
set underlineHeight(value: number);
/**
** @en
** Outline effect used to change the display, only for system fonts or TTF fonts.
**
** @zh
** 描边效果组件,用于字体描边,只能用于系统字体或 ttf 字体。
**/
get enableOutline(): boolean;
set enableOutline(value: boolean);
/**
* @en
* Outline color.
*
* @zh
* 改变描边的颜色。
*/
get outlineColor(): math.Color;
set outlineColor(value: math.Color);
/**
* @en
* Change the outline width.
*
* @zh
* 改变描边的宽度。
*/
get outlineWidth(): number;
set outlineWidth(value: number);
/**
* @en Shadow effect for Label component, only for system fonts or TTF fonts. Disabled when cache mode is char.
* @zh 用于给 Label 组件添加阴影效果，只能用于系统字体或 ttf 字体。在缓存模式为 char 时不可用。
*/
get enableShadow(): boolean;
set enableShadow(value: boolean);
/**
* @en
* Shadow color.
*
* @zh
* 阴影的颜色。
*/
get shadowColor(): math.Color;
set shadowColor(value: math.Color);
/**
* @en
* Offset between font and shadow.
*
* @zh
* 字体与阴影的偏移。
*/
get shadowOffset(): math.Vec2;
set shadowOffset(value: math.Vec2);
/**
* @en
* A non-negative float specifying the level of shadow blur.
*
* @zh
* 阴影的模糊程度。
*/
get shadowBlur(): number;
set shadowBlur(value: number);
/**
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get spriteFrame(): SpriteFrame | __private._cocos_2d_assembler_label_font_utils__LetterRenderTexture | null;
/**
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get ttfSpriteFrame(): SpriteFrame | null;
/**
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get assemblerData(): __private._cocos_2d_assembler_label_font_utils__ISharedLabelData | null;
/**
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
get fontAtlas(): __private._cocos_2d_assets_bitmap_font__FontAtlas | null;
set fontAtlas(value: __private._cocos_2d_assets_bitmap_font__FontAtlas | null);
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
get _bmFontOriginalSize(): number;
protected _string: string;
protected _horizontalAlign: HorizontalTextAlignment;
protected _verticalAlign: VerticalTextAlignment;
protected _actualFontSize: number;
protected _fontSize: number;
protected _fontFamily: string;
protected _lineHeight: number;
protected _overflow: Overflow;
protected _enableWrapText: boolean;
protected _font: Font | null;
protected _isSystemFontUsed: boolean;
protected _spacingX: number;
protected _isItalic: boolean;
protected _isBold: boolean;
protected _isUnderline: boolean;
protected _underlineHeight: number;
protected _cacheMode: CacheMode;
protected _enableOutline: boolean;
protected _outlineColor: math.Color;
protected _outlineWidth: number;
protected _enableShadow: boolean;
protected _shadowColor: math.Color;
protected _shadowOffset: math.Vec2;
protected _shadowBlur: number;
protected _N$file: Font | null;
protected _texture: SpriteFrame | __private._cocos_2d_assembler_label_font_utils__LetterRenderTexture | null;
protected _ttfSpriteFrame: SpriteFrame | null;
protected _userDefinedFont: Font | null;
protected _assemblerData: __private._cocos_2d_assembler_label_font_utils__ISharedLabelData | null;
protected _fontAtlas: __private._cocos_2d_assets_bitmap_font__FontAtlas | null;
protected _letterTexture: __private._cocos_2d_assembler_label_font_utils__LetterRenderTexture | null;
protected _contentWidth: number;
protected _textStyle: __private._cocos_2d_assembler_label_text_style__TextStyle | null;
protected _textLayout: __private._cocos_2d_assembler_label_text_layout__TextLayout | null;
protected _textRenderData: __private._cocos_2d_assembler_label_text_output_data__TextOutputRenderData | null;
protected _textLayoutData: __private._cocos_2d_assembler_label_text_output_data__TextOutputLayoutData | null;
constructor();
onEnable(): void;
_onPreDestroy(): void;
onDestroy(): void;
/**
* @en update render data.
* @zh 更新渲染相关数据。
* @param force @en Whether to force an immediate update. @zh 是否立马强制更新渲染数据。
*/
updateRenderData(force?: boolean): void;
protected _render(render: __private._cocos_2d_renderer_i_batcher__IBatcher): void;
protected _updateColor(): void;
/**
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
setEntityColor(color: math.Color): void;
protected _canRender(): boolean;
protected _flushAssembler(): void;
protected _applyFontTexture(): void;
protected changeMaterialForDefine(): void;
}
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export interface IRenderData {
x: number;
y: number;
z: number;
u: number;
v: number;
color: math.Color;
}
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export class BaseRenderData {
get vertexCount(): number;
get indexCount(): number;
get stride(): number;
get floatStride(): number;
get vertexFormat(): gfx.Attribute[];
get drawInfoType(): __private._cocos_2d_renderer_render_draw_info__RenderDrawInfoType;
set drawInfoType(type: __private._cocos_2d_renderer_render_draw_info__RenderDrawInfoType);
chunk: __private._cocos_2d_renderer_static_vb_accessor__StaticVBChunk;
protected _renderDrawInfo: __private._cocos_2d_renderer_render_draw_info__RenderDrawInfo;
get renderDrawInfo(): __private._cocos_2d_renderer_render_draw_info__RenderDrawInfo;
protected _material: Material | null;
get material(): Material | null;
set material(val: Material | null);
protected _dataHash: number;
get dataHash(): number;
set dataHash(val: number);
_isMeshBuffer: boolean;
protected _vc: number;
protected _ic: number;
protected _floatStride: number;
protected _vertexFormat: gfx.Attribute[];
protected _drawInfoType: __private._cocos_2d_renderer_render_draw_info__RenderDrawInfoType;
protected _multiOwner: boolean;
get multiOwner(): boolean;
set multiOwner(val: boolean);
protected _batcher: UI | null;
get batcher(): UI;
constructor(vertexFormat?: gfx.Attribute[]);
isValid(): false | __private._cocos_2d_renderer_static_vb_accessor__StaticVBAccessor;
initRenderDrawInfo(comp: UIRenderer, drawInfoType?: __private._cocos_2d_renderer_render_draw_info__RenderDrawInfoType): void;
removeRenderDrawInfo(comp: UIRenderer): void;
protected setRenderDrawInfoAttributes(): void;
}
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export class RenderData extends BaseRenderData {
static add(vertexFormat?: gfx.Attribute[], accessor?: __private._cocos_2d_renderer_static_vb_accessor__StaticVBAccessor): RenderData;
static remove(data: RenderData): void;
get dataLength(): number;
set dataLength(length: number);
get data(): IRenderData[];
_vertDirty: boolean;
get vertDirty(): boolean;
set vertDirty(val: boolean);
protected _textureHash: number;
get textureHash(): number;
set textureHash(val: number);
indices: Uint16Array | null;
set frame(val: SpriteFrame | __private._cocos_asset_assets_texture_base__TextureBase | null);
get frame(): SpriteFrame | __private._cocos_asset_assets_texture_base__TextureBase | null;
layer: number;
nodeDirty: boolean;
passDirty: boolean;
textureDirty: boolean;
hashDirty: boolean;
protected _accessor: __private._cocos_2d_renderer_static_vb_accessor__StaticVBAccessor;
get accessor(): __private._cocos_2d_renderer_static_vb_accessor__StaticVBAccessor;
vertexRow: number;
vertexCol: number;
constructor(vertexFormat?: gfx.Attribute[], accessor?: __private._cocos_2d_renderer_static_vb_accessor__StaticVBAccessor);
resize(vertexCount: number, indexCount: number): void;
protected setRenderDrawInfoAttributes(): void;
/**
* @internal
*/
fillDrawInfoAttributes(drawInfo: __private._cocos_2d_renderer_render_draw_info__RenderDrawInfo): void;
protected syncRender2dBuffer(): void;
resizeAndCopy(vertexCount: number, indexCount: number): void;
getMeshBuffer(): MeshBuffer | null;
updateNode(comp: UIRenderer): void;
updatePass(comp: UIRenderer): void;
updateTexture(frame: SpriteFrame | __private._cocos_asset_assets_texture_base__TextureBase): void;
updateHash(): void;
updateRenderData(comp: UIRenderer, frame: SpriteFrame | __private._cocos_asset_assets_texture_base__TextureBase): void;
clear(): void;
static createStaticVBAccessor(attributes: gfx.Attribute[], vCount?: number, iCount?: number): __private._cocos_2d_renderer_static_vb_accessor__StaticVBAccessor;
}
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export class MeshRenderData extends BaseRenderData {
static add(vertexFormat?: gfx.Attribute[]): MeshRenderData;
static remove(data: MeshRenderData): void;
/**
* @deprecated
*/
set formatByte(value: number);
get formatByte(): number;
get floatStride(): number;
/**
* Index of Float32Array: vData
*/
get vDataOffset(): number;
_isMeshBuffer: boolean;
vData: Float32Array;
iData: Uint16Array;
/**
* First vertex used in the current IA
*/
vertexStart: number;
/**
* Vertex count used in the current IA
*/
vertexRange: number;
/**
* First index used in the current IA
*/
indexStart: number;
/**
* Index count used in the current IA
*/
indexRange: number;
lastFilledIndex: number;
lastFilledVertex: number;
frame: any;
constructor(vertexFormat?: gfx.Attribute[]);
request(vertexCount: number, indexCount: number): boolean;
reserve(vertexCount: number, indexCount: number): boolean;
resize(vertexCount: number, indexCount: number): void;
updateRange(vertOffset: number, vertexCount: number, indexOffset: number, indexCount: number): void;
requestIA(device: gfx.Device): gfx.InputAssembler;
uploadBuffers(): void;
freeIAPool(): void;
reset(): void;
clear(): void;
protected _initIAInfo(device: gfx.Device): void;
protected _reallocBuffer(vCount: any, iCount: any): void;
setRenderDrawInfoAttributes(): void;
particleInitRenderDrawInfo(entity: __private._cocos_2d_renderer_render_entity__RenderEntity): void;
}
/**
* @internal
*/
export interface IAssembler {
[key: string]: any;
}
/**
* @internal
*/
export interface IAssemblerManager {
getAssembler(component: UIRenderer): IAssembler;
}
export namespace UIVertexFormat {
/**
* @en Get total components count for all attributes per vertex.
* @zh 获取每个顶点上所有属性的分量数总和
* @param attrs All attributes of the vertex format
* @returns Total components count
*/
export function getComponentPerVertex(attrs: gfx.Attribute[]): number;
/**
* @en Get total stride for all attributes per vertex.
* @zh 获取每个顶点上所有属性的总步进
* @param attrs All attributes of the vertex format
* @returns Total stride
*/
export function getAttributeStride(attrs: gfx.Attribute[]): number;
/**
* @en Vertex format with vector 3 position attribute
* @zh 包含三维位置属性的顶点格式
*/
export const vfmt: gfx.Attribute[];
/**
* @en Vertex format with the following layout.
* 1. Vector 3 position attribute (Float32)
* 2. Vector 4 color attribute (Float32)
* @zh 包含以下数据的顶点格式
* 1. 三维位置属性（Float32）
* 2. RGBA 颜色属性（Float32）
*/
export const vfmtPosColor: gfx.Attribute[];
/**
* @en Vertex format with the following layout
* 1. Vector 3 position attribute (Float32)
* 2. Vector 2 uv attribute (Float32)
* 3. Vector 4 color attribute (Float32)
* @zh 包含以下数据的顶点格式
* 1. 三维位置属性（Float32）
* 2. 二维贴图 UV 属性（Float32）
* 3. RGBA 颜色属性（Float32）
*/
export const vfmtPosUvColor: gfx.Attribute[];
/**
* @en Vertex format with the following layout
* 1. Vector 3 position attribute (Float32)
* 2. Vector 2 uv attribute (Float32)
* 3. Byte 4 color attribute (Byte)
* @zh 包含以下数据的顶点格式
* 1. 三维位置属性（Float32）
* 2. 二维贴图 UV 属性（Float32）
* 3. RGBA 颜色属性（Byte）
*/
export const vfmtPosUvColor4B: gfx.Attribute[];
/**
* @en Vertex format with the following layout
* 1. Vector 3 position attribute (Float32)
* 2. Vector 2 uv attribute (Float32)
* 3. First vector 4 color attribute (Float32)
* 4. Second vector 4 color attribute (Float32)
* @zh 包含以下数据的顶点格式
* 1. 三维位置属性（Float32）
* 2. 二维贴图 UV 属性（Float32）
* 3. 第一套 RGBA 颜色属性（Float32）
* 4. 第二套 RGBA 颜色属性（Float32）
*/
export const vfmtPosUvTwoColor: gfx.Attribute[];
/**
* @en Vertex format with the following layout
* 1. Vector 3 position attribute (Float32)
* 2. Vector 2 uv attribute (Float32)
* 3. First byte 4 color attribute (Byte)
* 4. Second byte 4 color attribute (Byte)
* @zh 包含以下数据的顶点格式
* 1. 三维位置属性（Float32）
* 2. 二维贴图 UV 属性（Float32）
* 3. 第一套 RGBA 颜色属性（Byte）
* 4. 第二套 RGBA 颜色属性（Byte）
*/
export const vfmtPosUvTwoColor4B: gfx.Attribute[];
}
/**
* @en UI rendering process
* @zh UI 渲染流程
*/
export class UI implements __private._cocos_2d_renderer_i_batcher__IBatcher {
protected _nativeObj: __private._cocos_2d_renderer_native_2d__NativeBatcher2d;
get nativeObj(): __private._cocos_2d_renderer_native_2d__NativeBatcher2d;
get currBufferAccessor(): __private._cocos_2d_renderer_static_vb_accessor__StaticVBAccessor;
get batches(): memop.CachedArray<__private._cocos_2d_renderer_draw_batch__DrawBatch2D>;
set currStaticRoot(value: UIStaticBatch | null);
set currIsStatic(value: boolean);
device: gfx.Device;
constructor(_root: Root);
initialize(): boolean;
destroy(): void;
/**
* @en
* Add the managed Canvas.
*
* @zh
* 添加屏幕组件管理。
*
* @param comp @en The render root of 2d.
* @zh 2d 渲染入口组件。
*/
addScreen(comp: RenderRoot2D): void;
/**
* @zh
* Removes the Canvas from the list.
*
* @param comp @en The target to removed.
* @zh 被移除的屏幕。
*/
removeScreen(comp: RenderRoot2D): void;
sortScreens(): void;
getFirstRenderCamera(node: Node): renderer.scene.Camera | null;
update(): void;
uploadBuffers(): void;
reset(): void;
/**
* @zh 如果有必要，为相应的顶点布局切换网格缓冲区。
* @en Switch the mesh buffer for corresponding vertex layout if necessary.
* @param attributes use VertexFormat.vfmtPosUvColor by default
*/
switchBufferAccessor(attributes?: gfx.Attribute[]): __private._cocos_2d_renderer_static_vb_accessor__StaticVBAccessor;
registerBufferAccessor(key: number, accessor: __private._cocos_2d_renderer_static_vb_accessor__StaticVBAccessor): void;
updateBuffer(attributes: gfx.Attribute[], bid: number): void;
/**
* @en
* Render component data submission process of UI.
* The submitted vertex data is the UI for world coordinates.
* For example: The UI components except Graphics and UIModel.
*
* @zh
* UI 渲染组件数据提交流程（针对提交的顶点数据是世界坐标的提交流程，例如：除 Graphics 和 UIModel 的大部分 ui 组件）。
* 此处的数据最终会生成需要提交渲染的 model 数据。
*
* @param comp - The committed renderable component
* @param renderData - The render data being committed
* @param frame - Texture or sprite frame related to the draw batch, could be null
* @param assembler - The assembler for the current component, could be null
* @param transform - Node type transform, if passed, then batcher will consider it's using model matrix, could be null
*/
commitComp(comp: UIRenderer, renderData: BaseRenderData | null, frame: __private._cocos_asset_assets_texture_base__TextureBase | SpriteFrame | null, assembler: any, transform: Node | null): void;
/**
* @en
* Render component data submission process for individual [[gfx.InputAssembler]]
* @zh
* 渲染组件中针对独立 [[gfx.InputAssembler]] 的提交流程
* 例如：Spine 和 DragonBones 等包含动态数据和材质的组件在内部管理 IA 并提交批次
* @param comp - The committed renderable component
* @param ia - The committed [[gfx.InputAssembler]]
* @param tex - The texture used
* @param mat - The material used
* @param [transform] - The related node transform if the render data is based on node's local coordinates
* @deprecated since v3.6.2, please use [[commitMiddleware]] instead
*/
commitIA(renderComp: UIRenderer, ia: gfx.InputAssembler, tex?: __private._cocos_asset_assets_texture_base__TextureBase, mat?: Material, transform?: Node): void;
/**
* @en
* Render component data submission process for middleware2d components
* @zh
* 渲染组件中针对2D中间件组件渲染数据的提交流程
* 例如：Spine 和 DragonBones 包含动态数据和材质的组件
* @param comp - The committed renderable component
* @param meshBuffer - The MeshBuffer used
* @param indexOffset - indices offset
* @param indexCount - indices count
* @param tex - The texture used
* @param mat - The material used
* @param enableBatch - component support multi draw batch or not
*/
commitMiddleware(comp: UIRenderer, meshBuffer: MeshBuffer, indexOffset: number, indexCount: number, tex: __private._cocos_asset_assets_texture_base__TextureBase, mat: Material, enableBatch: boolean): void;
/**
* @en
* Render component data submission process of UI.
* The submitted vertex data is the UI for local coordinates.
* For example: The UI components of Graphics and UIModel.
*
* @zh
* UI 渲染组件数据提交流程（针对例如： Graphics 和 UIModel 等数据量较为庞大的 ui 组件）。
*
* @param comp - The committed renderable component
* @param model - The committed model
* @param mat - The material used, could be null
*/
commitModel(comp: UIMeshRenderer | UIRenderer, model: renderer.scene.Model | null, mat: Material | null): void;
setupStaticBatch(staticComp: UIStaticBatch, bufferAccessor: __private._cocos_2d_renderer_static_vb_accessor__StaticVBAccessor): void;
endStaticBatch(): void;
/**
* @en
* Submit separate render data.
* This data does not participate in the batch.
*
* @zh
* 提交独立渲染数据.
* @param comp @en The UIStaticBatch component.
* @zh 静态组件
*/
commitStaticBatch(comp: UIStaticBatch): void;
/**
* @en
* End a section of render data and submit according to the batch condition.
*
* @zh
* 根据合批条件，结束一段渲染数据并提交。
*/
autoMergeBatches(renderComp?: UIRenderer): void;
/**
* @en
* Force changes to current batch data and merge
*
* @zh
* 强行修改当前批次数据并合并。
*
* @param material @en The material of the current batch.
* @zh 当前批次的材质。
* @param sprite @en Sprite frame of current batch.
* @zh 当前批次的精灵帧。
*/
forceMergeBatches(material: Material, frame: __private._cocos_asset_assets_texture_base__TextureBase | SpriteFrame | null, renderComp: UIRenderer): void;
resetRenderStates(): void;
/**
* @en
* Forced to merge the data of the previous batch to start a new batch.
*
* @zh
* 强制合并上一个批次的数据，开启新一轮合批。
*/
finishMergeBatches(): void;
/**
* @en
* Force to change the current material.
*
* @zh
* 强制刷新材质。
*/
flushMaterial(mat: Material): void;
walk(node: Node, level?: number): void;
syncMeshBuffersToNative(accId: number, buffers: MeshBuffer[]): void;
}
/**
* @deprecated since v3.6.0, this is an engine private interface that will be removed in the future.
* @internal
*/
export class UIDrawBatch extends __private._cocos_2d_renderer_draw_batch__DrawBatch2D {
}
export class QuadRenderData extends MeshRenderData {
constructor(vertexFormat: any);
}
/**
* @en A utils class for parsing HTML texts. The parsed results will be an object array.
* @zh 一个用于解析HTML文本的工具类。解析后的结果将是一个对象数组。
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export interface IHtmlTextParserResultObj {
text?: string;
style?: IHtmlTextParserStack;
}
/**
* @en Html Text Parser Stack interface
* @zh Html 文本解析器接口
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export interface IHtmlTextParserStack {
color?: string;
size?: number;
event?: {
[k: string]: string;
};
isNewLine?: boolean;
isImage?: boolean;
src?: string;
imageWidth?: number;
imageHeight?: number;
imageOffset?: string;
imageAlign?: string;
underline?: boolean;
italic?: boolean;
bold?: boolean;
outline?: {
color: string;
width: number;
};
}
/**
* @en Html Text Parser Stack
* @zh Html 文本解析器
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export class HtmlTextParser {
constructor();
parse(htmlString: string): IHtmlTextParserResultObj[];
}
export function getBaselineOffset(): number;
/**
* @deprecated since v3.7.2, this is an engine private interface that will be removed in the future.
*/
export function isUnicodeCJK(ch: string): boolean;
/**
* @deprecated since v3.7.2, this is an engine private interface that will be removed in the future.
*/
export function isUnicodeSpace(ch: string): boolean;
/**
* @deprecated since v3.7.2, this is an engine private interface that will be removed in the future.
*/
export function safeMeasureText(ctx: CanvasRenderingContext2D, string: string, desc?: string): number;
export function getSymbolLength(str: string): number;
export function getSymbolAt(str: string, index: number): string;
export function getSymbolCodeAt(str: string, index: number): string;
/**
* @deprecated since v3.7.2, this is an engine private interface that will be removed in the future.
*/
export function fragmentText(stringToken: string, allWidth: number, maxWidth: number, measureText: (string: string) => number): string[];
export const BASELINE_RATIO = 0.26;
export const MIDDLE_RATIO: number;
export class LRUCache {
constructor(size: any);
moveToHead(node: any): void;
put(key: any, value: any): void;
remove(node: any): void;
get(key: any): number | null;
clear(): void;
has(key: any): boolean;
delete(key: any): void;
}
/**
* @en The dynamic atlas manager which manages all runtime dynamic packed atlas texture for UI rendering.
* It generates a maximum of [[maxAtlasCount]] atlas texture, all atlas texture have the size of [[textureSize]].
* Normally the [[Root.batcher2D]] is in charge of submitting sprite frames to the dynamic atlas manager, the process is transparent to user.
* Note that the first committed sprite frame will define the filter settings of the atlas textures,
* only sprite frame with the same setting will be accepted afterward.
* @zh 动态合图的管理器，管理所有运行时动态合成的图集，主要用于 UI 渲染。
* 该管理器支持生成 [[maxAtlasCount]] 张动态合图，并且所有合图都有同样的 [[textureSize]] 像素尺寸。
* 一般来说 [[Root.batcher2D]] 负责提交 [[SpriteFrame]] 到动态合图管理器中，这个过程对于开发者是透明的。
* 需要注意的是，第一个提交的 [[SpriteFrame]] 会决定图集的过滤器参数，在此之后只有同样参数的贴图才会被管理器接受。
*/
export class DynamicAtlasManager extends System {
static instance: DynamicAtlasManager;
/**
* @en
* Enable or disable the dynamic atlas.
*
* @zh
* 开启或关闭动态图集。
*/
get enabled(): boolean;
set enabled(value: boolean);
/**
* @en
* The maximum number of atlases that can be created.
*
* @zh
* 可以创建的最大图集数量。
*/
get maxAtlasCount(): number;
set maxAtlasCount(value: number);
/**
* @en
* Get the current created atlas count.
*
* @zh
* 获取当前已经创建的图集数量。
*/
get atlasCount(): number;
/**
* @en
* Whether to enable textureBleeding.
*
* @zh
* 是否开启 textureBleeding。
*/
get textureBleeding(): boolean;
set textureBleeding(enable: boolean);
/**
* @en
* The size of the created atlas.
*
* @zh
* 创建的图集的宽高。
*/
get textureSize(): number;
set textureSize(value: number);
/**
* @en
* The maximum size of the picture that can be added to the atlas.
*
* @zh
* 可以添加进图集的图片的最大尺寸。
*/
get maxFrameSize(): number;
set maxFrameSize(value: number);
/**
* @internal
*/
init(): void;
/**
* @en
* Append a sprite frame into the dynamic atlas.
*
* @zh
* 添加碎图进入动态图集。
*
* @method insertSpriteFrame
* @param spriteFrame the sprite frame that will be inserted in the atlas.
*/
insertSpriteFrame(spriteFrame: any): {
x: number;
y: number;
texture: __private._cocos_2d_utils_dynamic_atlas_atlas__DynamicAtlasTexture;
} | null;
/**
* @en
* Reset all dynamic atlases, and all existing ones will be destroyed.
*
* @zh
* 重置所有动态图集，已有的动态图集会被销毁。
*
* @method reset
*/
reset(): void;
/**
* @en
* Delete a sprite from the atlas.
*
* @zh
* 从动态图集中删除某张碎图。
*
* @method deleteAtlasSpriteFrame
* @param spriteFrame the sprite frame that will be removed from the atlas.
*/
deleteAtlasSpriteFrame(spriteFrame: any): void;
/**
* @en
* Delete a texture from the atlas.
*
* @zh
* 从动态图集中删除某张纹理。
*
* @method deleteAtlasTexture
* @param texture the texture that will be removed from the atlas.
*/
deleteAtlasTexture(texture: any): void;
/**
* @en
* Pack the sprite in the dynamic atlas and update the atlas information of the sprite frame.
*
* @zh
* 将图片打入动态图集，并更新该图片的图集信息。
*
* @method packToDynamicAtlas
* @param frame the sprite frame that will be packed in the dynamic atlas.
*/
packToDynamicAtlas(comp: any, frame: any): void;
}
/**
* @en The singleton instance of [[DynamicAtlasManager]], please use [[DynamicAtlasManager.instance]] instead.
* @zh [[DynamicAtlasManager]] 的单例对象，请直接使用 [[DynamicAtlasManager.instance]]。
* @deprecated since v3.7
*/
export const dynamicAtlasManager: DynamicAtlasManager;
export namespace utils {
/**
* @en Finds a node by hierarchy path, the path is case-sensitive.
* It will traverse the hierarchy by splitting the path using '/' character.
* This function will still returns the node even if it is inactive.
* It is recommended to not use this function every frame instead cache the result at startup.
* @zh 通过路径从节点树中查找节点的方法，路径是大小写敏感的，并且通过 `/` 来分隔节点层级。
* 即使节点的状态是未启用的也可以找到，建议将结果缓存，而不是每次需要都去查找。
* @param path The path of the target node
* @param referenceNode If given, the search will be limited in the sub node tree of the reference node
*/
export function find(path: string, referenceNode?: Node): Node | null;
/**
* @en
* save a color buffer to a PPM file
* @zh
* 保存一个颜色缓冲到 PPM 文件中
* @param buffer color buffer
* @param w width
* @param h height
*/
export function toPPM(buffer: Uint8Array, w: number, h: number): string;
export function readMesh(mesh: Mesh, iPrimitive?: number): primitives.IGeometry;
/**
* @deprecated
*/
export function createMesh(geometry: primitives.IGeometry, out?: Mesh, options?: primitives.ICreateMeshOptions): Mesh;
export namespace createMesh {
/**
* @deprecated
*/
export interface IOptions {
/**
* @en calculate mesh's aabb or not
* @zh 是否计算模型的包围盒。
*/
calculateBounds?: boolean;
}
}
/**
* @en mesh utility class, use to create mesh.
* @zh 网格工具类，用于创建网格。
*/
export class MeshUtils {
/**
* @en create a static mesh.
* @zh 创建一个静态网格。
* @param geometry @en geometry data use for creating @zh 用于创建的几何数据
* @param out @en output static mesh @zh 输出的静态网格
* @param options @en options of creating @zh 创建选项
* @return @en The created static mesh, which is same as out @zh 新创建的静态网格，同 out 参数
*/
static createMesh(geometry: primitives.IGeometry, out?: Mesh, options?: primitives.ICreateMeshOptions): Mesh;
/**
* @en create a dynamic mesh.
* @zh 创建一个动态网格。
* @param primitiveIndex @en sub mesh index @zh 子网格索引
* @param geometry @en geometry data use for creating @zh 用于创建的几何数据
* @param out @en output dynamic mesh @zh 输出的动态网格
* @param options @en options of creating @zh 创建选项
* @return @en The created dynamic mesh, which is same as out @zh 新创建的动态网格，同 out 参数
*/
static createDynamicMesh(primitiveIndex: number, geometry: primitives.IDynamicGeometry, out?: Mesh, options?: primitives.ICreateDynamicMeshOptions): Mesh;
}
export function readBuffer(target: DataView, format?: gfx.Format, offset?: number, length?: number, stride?: number, out?: number[]): number[];
export function writeBuffer(target: DataView, data: number[], format?: gfx.Format, offset?: number, stride?: number): void;
export function mapBuffer(target: DataView, callback: (cur: number, idx: number, view: DataView) => number, format?: gfx.Format, offset?: number, length?: number, stride?: number, out?: DataView): DataView;
}
/**
* @en Utility for 3d model static batching
* @zh 服务于 3D 模型静态合批的工具类
*/
export class BatchingUtility {
/**
* @en
* Collect the Models under `staticModelRoot`,
* merge all the meshes statically into one (while disabling each component),
* and attach it to a new Model on `batchedRoot`.
* The world transform of each model is guaranteed to be preserved.
*
* For a more fine-grained control over the process, use `Mesh.merge` directly.
* @zh
* 在`staticModelRoot`下收集模型。
* 将所有的网格静态地合并成一个（同时禁用每个组件）。
* 并将其附加到 `batchedRoot` 上的一个新模型。
* 每个模型的世界变换都被保证保留下来。
* 如果要对这个过程进行更精细的控制，可以直接使用 `Mesh.merge`。
* @param staticModelRoot root of all the static models to be batched
* @param batchedRoot the target output node
*/
static batchStaticModel(staticModelRoot: Node, batchedRoot: Node): boolean;
/**
* @en
* Undoes everything `batchStaticModel` did.
* @zh
* 回退 `batchStaticModel` 做的工作
*
* @param staticModelRoot root of all the static models to be batched
* @param batchedRoot the target output node
*/
static unbatchStaticModel(staticModelRoot: Node, batchedRoot: Node): boolean;
}
/**
* @en A representation of a mesh asset
* A mesh can contain multiple sub-mesh resources. The mesh mainly provides data such as vertices and indices for model instances.
* @zh 代表一个网格资源
* 一个网格可包含多个子网格资源，网格主要为模型实例提供顶点，索引等数据
*/
export class Mesh extends Asset {
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
get _nativeAsset(): ArrayBuffer;
set _nativeAsset(value: ArrayBuffer);
/**
* @en The sub meshes count of the mesh.
* @zh 此网格的子网格数量。
* @deprecated Please use [[renderingSubMeshes.length]] instead
*/
get subMeshCount(): number;
/**
* @en The minimum position of all vertices in the mesh
* @zh （各分量都）小于等于此网格任何顶点位置的最大位置。
* @deprecated Please use [[struct.minPosition]] instead
*/
get minPosition(): Readonly | undefined;
/**
* @en The maximum position of all vertices in the mesh
* @zh （各分量都）大于等于此网格任何顶点位置的最大位置。
* @deprecated Please use [[struct.maxPosition]] instead
*/
get maxPosition(): Readonly | undefined;
/**
* @en The struct of the mesh
* @zh 此网格的结构。
*/
get struct(): Mesh.IStruct;
/**
* @en The actual data of the mesh
* @zh 此网格的数据。
*/
get data(): Uint8Array;
/**
* @en The hash of the mesh
* @zh 此网格的哈希值。
*/
get hash(): number;
/**
* @en The index of the joint buffer of all sub meshes in the joint map buffers
* @zh 所有子网格的关节索引集合
*/
get jointBufferIndices(): number[];
/**
* @en The sub meshes for rendering. Mesh could be split into different sub meshes for rendering.
* @zh 此网格创建的渲染网格。
*/
get renderingSubMeshes(): RenderingSubMesh[];
/**
* @en morph rendering data
* @zh 变形渲染数据
*/
morphRendering: __private._cocos_3d_assets_morph_rendering__MorphRendering | null;
constructor();
/**
* @en complete loading callback
* @zh 加载完成回调
*/
onLoaded(): void;
/**
* @en mesh init
* @zh 网格初始化函数
*/
initialize(): void;
/**
* @en update dynamic sub mesh geometry
* @zh 更新动态子网格的几何数据
* @param primitiveIndex @en sub mesh index @zh 子网格索引
* @param dynamicGeometry @en sub mesh geometry data @zh 子网格几何数据
*/
updateSubMesh(primitiveIndex: number, dynamicGeometry: primitives.IDynamicGeometry): void;
/**
* @en Destroy the mesh and release all related GPU resources
* @zh 销毁此网格，并释放它占有的所有 GPU 资源。
*/
destroy(): boolean;
/**
* @en Release all related GPU resources
* @zh 释放此网格占有的所有 GPU 资源。
*/
destroyRenderingMesh(): void;
/**
* @en Reset the struct and data of the mesh
* @zh 重置此网格的结构和数据。
* @param struct @en The new struct @zh 新结构
* @param data @en The new data @zh 新数据
* @deprecated Will be removed in v3.0.0, please use [[reset]] instead
*/
assign(struct: Mesh.IStruct, data: Uint8Array): void;
/**
* @en Reset the mesh with mesh creation information
* @zh 重置此网格。
* @param info @en Mesh creation information including struct and data @zh 网格创建信息，包含结构及数据
*/
reset(info: Mesh.ICreateInfo): void;
/**
* @en Get [[geometry.AABB]] bounds in the skeleton's bone space
* @zh 获取骨骼变换空间内下的 [[geometry.AABB]] 包围盒
* @param skeleton @en skeleton data @zh 骨骼信息
* @param skeleton @en skeleton data @zh 骨骼信息
*/
getBoneSpaceBounds(skeleton: Skeleton): (geometry.AABB | null)[];
/**
* @en Merge the given mesh into the current mesh
* @zh 合并指定的网格到此网格中。
* @param mesh @en The mesh to be merged @zh 要合并的网格
* @param worldMatrix @en The world matrix of the given mesh @zh 给定网格的模型变换矩阵
* @param validate @en Whether to validate the mesh @zh 是否验证网格顶点布局
* @returns @en whether the merging was successful or not @zh 返回合并成功与否
*/
merge(mesh: Mesh, worldMatrix?: math.Mat4, validate?: boolean): boolean;
/**
* @en Validation for whether the given mesh can be merged into the current mesh.
* To pass the validation, it must satisfy either of these two requirements:
* - When the current mesh have no data
* - When the two mesh have the same vertex bundle count, the same sub meshes count, and the same sub mesh layout.
*
* Same mesh layout means:
* - They have the same primitive type and reference to the same amount vertex bundle with the same indices.
* - And they all have or don't have index view
* @zh 验证指定网格是否可以合并至当前网格。
*
* 当满足以下条件之一时，指定网格可以合并至当前网格：
* - 当前网格无数据而待合并网格有数据；
* - 它们的顶点块数目相同且对应顶点块的布局一致，并且它们的子网格数目相同且对应子网格的布局一致。
*
* 两个顶点块布局一致当且仅当：
* - 它们具有相同数量的顶点属性且对应的顶点属性具有相同的属性格式。
*
* 两个子网格布局一致，当且仅当：
* - 它们具有相同的图元类型并且引用相同数量、相同索引的顶点块；并且，
* - 要么都需要索引绘制，要么都不需要索引绘制。
* @param mesh @en The other mesh to be validated @zh 待验证的网格
*/
validateMergingMesh(mesh: Mesh): boolean;
/**
* @en Read the requested attribute of the given sub mesh
* @zh 读取子网格的指定属性。
* @param primitiveIndex @en Sub mesh index @zh 子网格索引
* @param attributeName @en Attribute name @zh 属性名称
* @returns @en Return null if not found or can't read, otherwise, will create a large enough typed array to contain all data of the attribute,
* the array type will match the data type of the attribute. @zh 读取失败返回 null， 否则返回对应的类型数组
*/
readAttribute(primitiveIndex: number, attributeName: gfx.AttributeName): __private.__types_globals__TypedArray | null;
/**
* @en Read the requested attribute of the given sub mesh and fill into the given buffer.
* @zh 读取子网格的指定属性到目标缓冲区中。
* @param primitiveIndex @en Sub mesh index @zh 子网格索引
* @param attributeName @en Attribute name @zh 属性名称
* @param buffer @en The target array buffer @zh 目标缓冲区
* @param stride @en attribute stride @zh 属性跨距
* @param offset @en The offset of the first attribute in the target buffer @zh 第一个属性在目标缓冲区的偏移
* @returns @en false if failed to access attribute, true otherwise @zh 是否成功拷贝
*/
copyAttribute(primitiveIndex: number, attributeName: gfx.AttributeName, buffer: ArrayBuffer, stride: number, offset: number): boolean;
/**
* @en Read the indices data of the given sub mesh
* @zh 读取子网格的索引数据。
* @param primitiveIndex @en Sub mesh index @zh 子网格索引
* @returns @en Return null if not found or can't read, otherwise, will create a large enough typed array to contain all indices data,
* the array type will use the corresponding stride size. @zh 读取失败返回 null，否则返回索引数据
*/
readIndices(primitiveIndex: number): Uint8Array | Uint16Array | Uint32Array | null;
/**
* @en Read the indices data of the given sub mesh and fill into the given array
* @zh 读取子网格的索引数据到目标数组中。
* @param primitiveIndex @en Sub mesh index @zh 子网格索引
* @param outputArray @en The target output array @zh 目标索引数组
* @returns @en Return false if failed to access the indices data, return true otherwise. @zh 拷贝失败返回 false， 否则返回 true
*/
copyIndices(primitiveIndex: number, outputArray: number[] | ArrayBufferView): boolean;
/**
* @en Read the format by attributeName of submesh
* @zh 根据属性名读取子网格的属性信息。
* @param primitiveIndex @en Sub mesh index @zh 子网格索引
* @param attributeName @en Attribute name @zh 属性名称
* @returns @en Return null if failed to read format, return the format otherwise. @zh 读取失败返回 null， 否则返回 format
*/
readAttributeFormat(primitiveIndex: number, attributeName: gfx.AttributeName): gfx.FormatInfo | null;
/**
* @en default init
* @zh 默认初始化
* @param uuid @en asset uuid @zh 资源 uuid
*/
initDefault(uuid?: string): void;
/**
* @en Set whether the data of this mesh could be accessed (read or wrote), it could be used only for static mesh
* @zh 设置此网格的数据是否可被存取，此接口只针对静态网格资源生效
* @param allowDataAccess @en Indicate whether the data of this mesh could be accessed (read or wrote) @zh 是否允许存取网格数据
*/
set allowDataAccess(allowDataAccess: boolean);
/**
* @en Get whether the data of this mesh could be read or wrote
* @zh 获取此网格的数据是否可被存取
* @return @en whether the data of this mesh could be accessed (read or wrote) @zh 此网格的数据是否可被存取
*/
get allowDataAccess(): boolean;
}
export namespace Mesh {
export interface IBufferView {
offset: number;
length: number;
count: number;
stride: number;
}
/**
* @en Vertex bundle, it describes a set of interleaved vertex attributes and their values.
* @zh 顶点块。顶点块描述了一组**交错排列**（interleaved）的顶点属性并存储了顶点属性的实际数据。
* 交错排列是指在实际数据的缓冲区中，每个顶点的所有属性总是依次排列，并总是出现在下一个顶点的所有属性之前。
*/
export interface IVertexBundle {
/**
* @en The actual value for all vertex attributes.
* You must use DataView to access the data.
* Because there is no guarantee that the starting offsets of all properties are byte aligned as required by TypedArray.
* @zh 所有顶点属性的实际数据块。
* 你必须使用 DataView 来读取数据。
* 因为不能保证所有属性的起始偏移都按 TypedArray 要求的字节对齐。
*/
view: IBufferView;
/**
* @en All attributes included in the bundle
* @zh 包含的所有顶点属性。
*/
attributes: gfx.Attribute[];
}
export interface IMeshCluster {
clusterView: IBufferView;
triangleView: IBufferView;
vertexView: IBufferView;
coneView?: IBufferView;
}
/**
* @en Sub mesh contains a list of primitives with the same type (Point, Line or Triangle)
* @zh 子网格。子网格由一系列相同类型的图元组成（例如点、线、面等）。
*/
export interface ISubMesh {
/**
* @en The vertex bundle references used by the sub mesh.
* @zh 此子网格引用的顶点块，索引至网格的顶点块数组。
*/
vertexBundelIndices: number[];
/**
* @en The primitive mode of the sub mesh
* @zh 此子网格的图元类型。
*/
primitiveMode: gfx.PrimitiveMode;
/**
* @en The index data of the sub mesh
* @zh 此子网格使用的索引数据。
*/
indexView?: IBufferView;
/**
* @en The joint map index in [[IStruct.jointMaps]]. Could be absent
* @zh 此子网格使用的关节索引映射表在 [[IStruct.jointMaps]] 中的索引。
* 如未定义或指向的映射表不存在，则默认 VB 内所有关节索引数据直接对应骨骼资源数据。
*/
jointMapIndex?: number;
/**
* @en The cluster data of the sub mesh
*/
cluster?: IMeshCluster;
}
/**
* @en dynamic info used to create dyanmic mesh
* @zh 动态信息，用于创建动态网格
*/
export interface IDynamicInfo {
/**
* @en max submesh count
* @zh 最大子模型个数。
*/
maxSubMeshes: number;
/**
* @en max submesh vertex count
* @zh 子模型最大顶点个数。
*/
maxSubMeshVertices: number;
/**
* @en max submesh index count
* @zh 子模型最大索引个数。
*/
maxSubMeshIndices: number;
}
/**
* @en dynamic struct
* @zh 动态结构体
*/
export interface IDynamicStruct {
/**
* @en dynamic mesh info
* @zh 动态模型信息。
*/
info: IDynamicInfo;
/**
* @en dynamic submesh bounds
* @zh 动态子模型包围盒。
*/
bounds: geometry.AABB[];
}
/**
* @en The structure of the mesh
* @zh 描述了网格的结构。
*/
export interface IStruct {
/**
* @en All vertex bundles of the mesh
* @zh 此网格所有的顶点块。
*/
vertexBundles: IVertexBundle[];
/**
* @en All sub meshes
* @zh 此网格的所有子网格。
*/
primitives: ISubMesh[];
/**
* @en The minimum position of all vertices in the mesh
* @zh （各分量都）小于等于此网格任何顶点位置的最大位置。
*/
minPosition?: math.Vec3;
/**
* @en The maximum position of all vertices in the mesh
* @zh （各分量都）大于等于此网格任何顶点位置的最小位置。
*/
maxPosition?: math.Vec3;
/**
* @en The joint index map list.
* @zh 此网格使用的关节索引映射关系列表，数组长度应为子模型中实际使用到的所有关节，
* 每个元素都对应一个原骨骼资源里的索引，按子模型 VB 内的实际索引排列。
*/
jointMaps?: number[][];
/**
* @en The morph information of the mesh
* @zh 网格的形变数据
*/
morph?: Morph;
/**
* @en The specific data of the dynamic mesh
* @zh 动态网格特有数据
*/
dynamic?: IDynamicStruct;
/**
* @en Whether the mesh data is quantized to reduce memory usage
* @zh 此网格数据是否经过量化以减少内存占用。
*/
quantized?: boolean;
/**
* @en Whether the mesh data is encoded to reduce memory usage
* @zh
*/
encoded?: boolean;
/**
* @en Whether the mesh data is compressed to reduce memory usage
* @zh 此网格数据是否经过压缩以减少内存占用。
*/
compressed?: boolean;
/**
* @en Whether the mesh contains cluster data
* @zh 此网格是否包含 cluster 数据。
*/
cluster?: boolean;
}
/**
* @en The create info of the mesh
* @zh 网格创建信息
*/
export interface ICreateInfo {
/**
* @en Mesh structure
* @zh 网格结构。
*/
struct: Mesh.IStruct;
/**
* @en Mesh binary data
* @zh 网格二进制数据。
*/
data: Uint8Array;
}
}
/**
* @en The skeleton asset. It stores the path related to [[SkinnedMeshRenderer.skinningRoot]] of all bones and its bind pose matrix.
* @zh 骨骼资源。骨骼资源记录了每个关节（相对于 [[SkinnedMeshRenderer.skinningRoot]]）的路径以及它的绑定姿势矩阵。
*/
export class Skeleton extends Asset {
/**
* @en The path of all bones, the length always equals the length of [[bindposes]]
* @zh 所有关节的路径。该数组的长度始终与 [[bindposes]] 的长度相同。
*/
get joints(): string[];
set joints(value: string[]);
/**
* @en The bind poses matrix of all bones, the length always equals the length of [[joints]]
* @zh 所有关节的绑定姿势矩阵。该数组的长度始终与 [[joints]] 的长度相同。
*/
get bindposes(): math.Mat4[];
set bindposes(value: math.Mat4[]);
/**
* @en Gets the inverse bind poses matrix
* @zh 获取反向绑定姿势矩阵
*/
get inverseBindposes(): math.Mat4[];
/**
* @en Gets the hash of the skeleton asset
* @zh 获取骨骼资源的哈希值
*/
get hash(): number;
destroy(): boolean;
/**
* @en Check whether the skeleton is validate which means it has both joints and bindposes data.
* @zh 检查当前骨骼对象是否是有效的，取决于它是否包含关节路径和绑定姿势数据。
* @returns @en Whether the skeleton is valid or not @zh 此骨骼是否有效
*/
validate(): boolean;
}
/**
* @en Mesh morph data structure to describe the sub meshes data of all sub meshes,
* it also contains all sub mesh morphs, global weights configuration and target names.
* Normally the global weights configuration should be identical to the sub mesh morph weights,
* but if not, the global weights in morph is less prioritized.
* @zh 网格的形变数据结构，包含所有子网格形变数据，全局的权重配置和所有形变目标名称。
* 一般来说，全局权重配置和子网格形变数据中保持一致，但如果有差异，以子网格形变数据中的权重配置为准。
*/
export interface Morph {
/**
* Morph data of each sub-mesh.
*/
subMeshMorphs: (SubMeshMorph | null)[];
/**
* Common initial weights of each sub-mesh.
*/
weights?: number[];
/**
* Name of each target of each sub-mesh morph.
* This field is only meaningful if every sub-mesh has the same number of targets.
*/
targetNames?: string[];
}
/**
* @en Morph target contains all displacements data of each vertex attribute like position and normal.
* @zh 形变目标数据包含网格顶点属性在形变下的变化值，可能包含位移、法线等属性
*/
export interface MorphTarget {
/**
* Displacement of each target attribute.
*/
displacements: Mesh.IBufferView[];
}
/**
* @en Sub mesh morph data describes all morph targets for one sub mesh,
* including attributes in each morph target, morph targets data and weights corresponding each targets.
* @zh 子网格形变数据描述一个子网格下所有的形变目标数据，包含顶点形变属性，形变目标数据和对应每个形变目标的权重。
*/
export interface SubMeshMorph {
/**
* Attributes to morph.
*/
attributes: gfx.AttributeName[];
/**
* Targets.
*/
targets: MorphTarget[];
/**
* Initial weights of each target.
*/
weights?: number[];
}
/**
* @en Mesh renderer component for general 3d model rendering, it generates and link to a Model in the render scene.
* It supports real time lighting and shadow, baked light map, and morph rendering.
* @zh 用于通用模型渲染的网格渲染器组件，会创建并关联一个渲染场景中的模型对象。
* 该组件支持实时光照和阴影，预烘焙光照贴图和形变网格渲染。
*/
export class MeshRenderer extends ModelRenderer {
/**
* @en Shadow projection mode enumeration.
* @zh 阴影投射方式枚举。
*/
static ShadowCastingMode: {
/**
* @en Disable shadow projection.
* @zh 不投射阴影。
*/
OFF: number;
/**
* @en Enable shadow projection.
* @zh 开启阴影投射。
*/
ON: number;
};
/**
* @en Shadow receive mode enumeration.
* @zh 阴影接收方式枚举。
*/
static ShadowReceivingMode: {
/**
* @en Disable shadow receiving.
* @zh 不接收阴影。
*/
OFF: number;
/**
* @en Enable shadow receiving.
* @zh 开启阴影投射。
*/
ON: number;
};
/**
* @en The settings for GI baking, it was called lightmapSettings before
* @zh 全局光照烘焙的配置，以前名称为lightmapSettings
*/
bakeSettings: __private._cocos_3d_framework_mesh_renderer__ModelBakeSettings;
protected _mesh: Mesh | null;
protected _shadowCastingMode: number;
protected _shadowReceivingMode: number;
protected _shadowBias: number;
protected _shadowNormalBias: number;
protected _reflectionProbeId: number;
protected _reflectionProbeBlendId: number;
protected _reflectionProbeBlendWeight: number;
protected _enabledGlobalStandardSkinObject: boolean;
protected _reflectionProbeDataMap: Texture2D | null;
/**
* @en Local shadow bias for real time lighting.
* @zh 实时光照下模型局部的阴影偏移。
*/
get shadowBias(): number;
set shadowBias(val: number);
/**
* @en local shadow normal bias for real time lighting.
* @zh 实时光照下模型局部的阴影法线偏移。
*/
get shadowNormalBias(): number;
set shadowNormalBias(val: number);
/**
* @en Shadow projection mode.
* @zh 实时光照下阴影投射方式。
*/
get shadowCastingMode(): number;
set shadowCastingMode(val: number);
get shadowCastingModeForInspector(): boolean;
set shadowCastingModeForInspector(val: boolean);
/**
* @en Is received direction Light.
* @zh 是否接收平行光光照。
* @param visibility @en direction light visibility. @zh 方向光的可见性。
*/
onUpdateReceiveDirLight(visibility: number, forceClose?: boolean): void;
/**
* @en receive shadow.
* @zh 实时光照下是否接受阴影。
*/
get receiveShadow(): number;
set receiveShadow(val: number);
get receiveShadowForInspector(): boolean;
set receiveShadowForInspector(val: boolean);
/**
* @en Gets or sets the mesh of the model.
* Note, when set, all morph targets' weights would be reset to zero.
* @zh 获取或设置模型的网格数据。
* 注意，设置时，所有形变目标的权重都将归零。
*/
get mesh(): Mesh | null;
set mesh(val: Mesh | null);
/**
* @en Gets the model in [[RenderScene]].
* @zh 获取渲染场景 [[RenderScene]] 中对应的模型。
*/
get model(): renderer.scene.Model | null;
/**
* @en Whether to enable morph rendering.
* @zh 是否启用形变网格渲染。
*/
get enableMorph(): boolean;
set enableMorph(value: boolean);
/**
* @en Set the Separable-SSS skin standard model component.
* @zh 设置是否是全局的4s标准模型组件
*/
get isGlobalStandardSkinObject(): boolean;
set isGlobalStandardSkinObject(val: boolean);
protected _modelType: typeof renderer.scene.Model;
protected _model: renderer.scene.Model | null;
constructor();
onLoad(): void;
onRestore(): void;
onEnable(): void;
onDisable(): void;
onDestroy(): void;
onGeometryChanged(): void;
/**
* @zh 获取子网格指定形变目标的权重。
* @en Gets the weight at specified morph target of the specified sub mesh.
* @param subMeshIndex Index to the sub mesh.
* @param shapeIndex Index to the morph target of the sub mesh.
* @returns The weight.
*/
getWeight(subMeshIndex: number, shapeIndex: number): number;
/**
* @zh
* 设置子网格所有形变目标的权重。
* `subMeshIndex` 是无效索引或 `weights` 的长度不匹配子网格的形变目标数量时，此方法不会生效。
* @en
* Sets weights of each morph target of the specified sub mesh.
* If takes no effect if `subMeshIndex` is out of bounds or if `weights` has a different length with morph targets count of the sub mesh.
* @param weights The weights.
* @param subMeshIndex Index to the sub mesh.
*/
setWeights(weights: number[], subMeshIndex: number): void;
/**
* @zh
* 设置子网格指定外形的权重。
* `subMeshIndex` 或 `shapeIndex` 是无效索引时，此方法不会生效。
* @en
* Sets the weight at specified shape of specified sub mesh.
* If takes no effect if
* `subMeshIndex` or `shapeIndex` out of bounds.
* @param weight The weight.
* @param subMeshIndex Index to the sub mesh.
* @param shapeIndex Index to the shape of the sub mesh.
*/
setWeight(weight: number, subMeshIndex: number, shapeIndex: number): void;
setInstancedAttribute(name: string, value: ArrayLike): void;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
_updateLightmap(lightmap: Texture2D | null, uOff: number, vOff: number, scale: number, lum: number): void;
/**
* @zh
* 更新反射探针烘焙的cubemap。
* @en
* Updat cubemap baked with reflection probes.
* @param cubeMap baked cubemap.
* @param useDefaultTexture if the reflection probe has not been baked, is the skybox used instead.
*/
updateProbeCubemap(cubeMap: TextureCube | null): void;
/**
* @zh
* 更新用于混合的反射探针烘焙的cubemap。
* @en
* Updat cubemap baked with reflection probes for blending.
* @param cubeMap baked cubemap.
*/
updateProbeBlendCubemap(cubeMap: TextureCube | null): void;
/**
* @zh
* 更新平面反射渲染纹理。
* @en
* Update the reflection rendering texture.
* @param planarMap render texture.
*/
updateProbePlanarMap(planarMap: gfx.Texture | null): void;
/**
* @zh
* 更新反射探针的数据贴图。
* @en
* Update the data mapping of the reflection probe.
* @param dataMap data mapping with data saved all reflection probe data.
*/
updateReflectionProbeDataMap(dataMap: Texture2D | null): void;
/**
* @zh
* 更新反射探针的id。
* @en
* Update the id of the reflection probe.
* @param probeId probe id.
*/
updateReflectionProbeId(probeId: number): void;
/**
* @zh
* 更新用于混合的反射探针的id。
* @en
* Update the id of the reflection probe used for blending.
* @param blendProbeId probe id of blend.
*/
updateReflectionProbeBlendId(blendProbeId: number): void;
/**
* @zh
* 更新混合权重。
* @en
* Update blending weight.
* @param weight blending weight.
*/
updateReflectionProbeBlendWeight(weight: number): void;
protected _updateReflectionProbeTexture(): void;
protected _updateModels(): void;
protected _updateReceiveDirLight(): void;
protected _createModel(): void;
protected _attachToScene(): void;
protected _updateModelParams(): void;
protected _onUpdateLightingmap(): void;
protected _onUpdateLocalShadowBiasAndProbeId(): void;
protected _onUpdateLocalReflectionProbeData(): void;
protected _onUpdateReflectionProbeDataMap(): void;
protected _onMaterialModified(idx: number, material: Material | null): void;
protected _onMeshChanged(old: Mesh | null): void;
protected _clearMaterials(): void;
protected _getBuiltinMaterial(): Material;
protected _onVisibilityChange(val: number): void;
protected _updateShadowBias(): void;
protected _updateShadowNormalBias(): void;
protected _updateCastShadow(): void;
protected _updateReceiveShadow(): void;
protected onMobilityChanged(): void;
protected onLightProbeBakingChanged(): void;
protected onUseLightProbeChanged(): void;
protected onReflectionProbeChanged(): void;
protected onBakeToReflectionProbeChanged(): void;
protected _updateUseLightProbe(): void;
protected _isBatchingEnabled(): boolean;
protected _updateUseReflectionProbe(): void;
protected _updateUseReflectionProbeType(): void;
protected _updateBakeToReflectionProbe(): void;
}
export namespace MeshRenderer {
/**
* @en Shadow projection mode.
* @zh 阴影投射方式。
*/
export type ShadowCastingMode = __private.__types_globals__EnumAlias;
/**
* @en Shadow receive mode.
* @zh 阴影接收方式。
*/
export type ShadowReceivingMode = __private.__types_globals__EnumAlias;
}
/**
* @en The directional light component, only one real time directional light is permitted in one scene, it act as the main light of the scene.
* @zh 平行光源组件，一个场景只允许存在一个实时的平行光源，作为场景的主光源存在。
*/
export class DirectionalLight extends Light {
/**
* @en The light source intensity.
* @zh 光源强度。
*/
get illuminance(): number;
set illuminance(val: number);
/**
* @en Whether activate real time shadow.
* @zh 是否启用实时阴影？
*/
get shadowEnabled(): boolean;
set shadowEnabled(val: boolean);
/**
* @en The shadow pcf for real time shadow.
* @zh 实时阴影计算中的阴影 pcf 等级。
*/
get shadowPcf(): number;
set shadowPcf(val: number);
/**
* @en The shadow map sampler offset for real time shadow.
* @zh 实时阴影计算中的阴影纹理偏移值。
*/
get shadowBias(): number;
set shadowBias(val: number);
/**
* @en The global normal bias for real time shadow.
* @zh 实时阴影计算中的法线偏移。
*/
get shadowNormalBias(): number;
set shadowNormalBias(val: number);
/**
* @en The shadow color saturation for real time shadow.
* @zh 实时阴影计算中的阴影颜色饱和度。
*/
get shadowSaturation(): number;
set shadowSaturation(val: number);
/**
* @en The potential shadow distance from the camera for real time shadow.
* @zh 实时阴影计算中潜在阴影产生的范围
*/
get shadowDistance(): number;
set shadowDistance(val: number);
/**
* @en The occlusion range for real time shadow.
* @zh 实时阴影计算中剔除阴影的范围
*/
get shadowInvisibleOcclusionRange(): number;
set shadowInvisibleOcclusionRange(val: number);
/**
* @en get or set shadow CSM level
* @zh 获取或者设置阴影层级
*/
get csmLevel(): number;
set csmLevel(val: number);
/**
* @en enable csm
* @zh 开启或关闭 csm 模式
*/
get enableCSM(): boolean;
set enableCSM(val: boolean);
/**
* @en get or set shadow CSM level ratio
* @zh 获取或者设置阴影层级系数
*/
get csmLayerLambda(): number;
set csmLayerLambda(val: number);
/**
* @en get or set shadow CSM performance optimization mode
* @zh 获取或者设置级联阴影性能优化模式
* @internal
*/
get csmOptimizationMode(): number;
set csmOptimizationMode(val: number);
/**
* @en Whether to use fixed area shadow in real time shadow.
* @zh 实时阴影计算中是否使用固定区域阴影。
*/
get shadowFixedArea(): boolean;
set shadowFixedArea(val: boolean);
/**
* @en The near clip plane of the shadow camera for fixed area shadow
* @zh 固定区域阴影设置中阴影相机近裁剪面
*/
get shadowNear(): number;
set shadowNear(val: number);
/**
* @en The far clip plane of the shadow camera for fixed area shadow.
* @zh 固定区域阴影设置中阴影相机远裁剪面。
*/
get shadowFar(): number;
set shadowFar(val: number);
/**
* @en The orthogonal size of the shadow camera for fixed area shadow.
* @zh 固定区域阴影设置中阴影相机的正交尺寸
*/
get shadowOrthoSize(): number;
set shadowOrthoSize(val: number);
/**
* @en Enabled shadow advanced options
* @zh 是否启用高级选项？
*/
get csmAdvancedOptions(): boolean;
set csmAdvancedOptions(val: boolean);
/**
* @en Enabled csm layers transition
* @zh 是否启用级联阴影层级过渡？
*/
get csmLayersTransition(): boolean;
set csmLayersTransition(val: boolean);
/**
* @en get or set csm layers transition range
* @zh 获取或者设置级联阴影层级过渡范围？
*/
get csmTransitionRange(): number;
set csmTransitionRange(val: number);
constructor();
protected _createLight(): void;
protected _onUpdateReceiveDirLight(): void;
}
/**
* @en The base class of all light components, contains basic light settings for both real time light and baked light.
* @zh 光源组件基类，包含实时光源和烘焙光源的基本配置信息。
*/
export class Light extends Component {
/**
* @en The light type enumeration.
* @zh 光源类型枚举。
*/
static Type: typeof renderer.scene.LightType;
/**
* @en The physical term used for light.
* @zh 光源所使用的物理计量单位。
*/
static PhotometricTerm: {
LUMINOUS_FLUX: number;
LUMINANCE: number;
};
protected _color: math.Color;
protected _useColorTemperature: boolean;
protected _colorTemperature: number;
protected _staticSettings: __private._cocos_3d_lights_light_component__StaticLightSettings;
protected _visibility: number;
protected _type: renderer.scene.LightType;
protected _lightType: typeof renderer.scene.Light;
protected _light: renderer.scene.Light | null;
/**
* @en The color of the light.
* @zh 光源颜色。
*/
get color(): Readonly;
set color(val: Readonly);
/**
* @en
* Whether to enable light color temperature.
* @zh
* 是否启用光源色温。
*/
get useColorTemperature(): boolean;
set useColorTemperature(enable: boolean);
/**
* @en
* The light color temperature.
* @zh
* 光源色温。
*/
get colorTemperature(): number;
set colorTemperature(val: number);
/**
* @en
* static light settings.
* @zh
* 静态灯光设置。
*/
get staticSettings(): __private._cocos_3d_lights_light_component__StaticLightSettings;
set staticSettings(val: __private._cocos_3d_lights_light_component__StaticLightSettings);
/**
* @en The light type.
* @zh 光源类型。
*/
get type(): renderer.scene.LightType;
/**
* @en Whether the light is baked
* @zh 光源是否被烘焙
*/
get baked(): boolean;
set baked(val: boolean);
/**
* @en Visibility mask of the light, declaring a set of node layers that will be visible to this light.
* @zh 光照的可见性掩码，声明在当前光照中可见的节点层级集合。
*/
set visibility(vis: number);
get visibility(): number;
constructor();
onLoad(): void;
onEnable(): void;
onDisable(): void;
onDestroy(): void;
protected _createLight(): void;
protected _destroyLight(): void;
protected _attachToScene(): void;
protected _detachFromScene(): void;
protected _onUpdateReceiveDirLight(): void;
}
export namespace Light {
export type Type = __private.__types_globals__EnumAlias;
export type PhotometricTerm = __private.__types_globals__EnumAlias;
}
/**
* @en The sphere light component, multiple sphere lights can be added to one scene.
* @zh 球面光源组件，场景中可以添加多个球面光源。
*/
export class SphereLight extends Light {
/**
* @en Luminous flux of the light.
* @zh 光通量。
*/
get luminousFlux(): number;
set luminousFlux(val: number);
/**
* @en Luminance of the light.
* @zh 光亮度。
*/
get luminance(): number;
set luminance(val: number);
/**
* @en The photometric term currently being used.
* @zh 当前使用的光度学计量单位。
*/
get term(): number;
set term(val: number);
/**
* @en
* Size of the light.
* @zh
* 光源大小。
*/
get size(): number;
set size(val: number);
/**
* @en
* Range of the light.
* @zh
* 光源范围。
*/
get range(): number;
set range(val: number);
constructor();
protected _createLight(): void;
}
/**
* @en The spot light component, multiple spot lights can be added to one scene.
* @zh 聚光灯光源组件，场景中可以添加多个聚光灯光源。
*/
export class SpotLight extends Light {
/**
* @en Luminous flux of the light.
* @zh 光通量。
*/
get luminousFlux(): number;
set luminousFlux(val: number);
/**
* @en Luminance of the light.
* @zh 光亮度。
*/
get luminance(): number;
set luminance(val: number);
/**
* @en The photometric term currently being used.
* @zh 当前使用的光度学计量单位。
*/
get term(): number;
set term(val: number);
/**
* @en
* Size of the light.
* @zh
* 光源大小。
*/
get size(): number;
set size(val: number);
/**
* @en
* Range of the light.
* @zh
* 光源范围。
*/
get range(): number;
set range(val: number);
/**
* @en
* The spot light cone angle.
* @zh
* 聚光灯锥角。
*/
get spotAngle(): number;
set spotAngle(val: number);
/**
* @en The angle attenuation strength of the spot light.
* The larger the value, the softer the edge, and the smaller the value, the harder the edge.
* @zh 聚光灯角度衰减强度。值越大，边缘越柔和，值越小，边缘越硬。
*/
get angleAttenuationStrength(): number;
set angleAttenuationStrength(val: number);
/**
* @en Whether activate shadow
* @zh 是否启用阴影？
*/
get shadowEnabled(): boolean;
set shadowEnabled(val: boolean);
/**
* @en The pcf level of the shadow generation.
* @zh 获取或者设置阴影 pcf 等级。
*/
get shadowPcf(): number;
set shadowPcf(val: number);
/**
* @en The depth offset of shadow to avoid moire pattern artifacts
* @zh 阴影的深度偏移, 可以减弱跨像素导致的条纹状失真
*/
get shadowBias(): number;
set shadowBias(val: number);
/**
* @en The normal bias of the shadow map.
* @zh 设置或者获取法线偏移。
*/
get shadowNormalBias(): number;
set shadowNormalBias(val: number);
constructor();
protected _createLight(): void;
}
/**
* @en The point light component, multiple point lights can be added to one scene.
* @zh 点光源组件，场景中可以添加多个点光源。
*/
export class PointLight extends Light {
/**
* @en Luminous flux of the light.
* @zh 光通量。
*/
get luminousFlux(): number;
set luminousFlux(val: number);
/**
* @en Luminance of the light.
* @zh 光亮度。
*/
get luminance(): number;
set luminance(val: number);
/**
* @en The photometric term currently being used.
* @zh 当前使用的光度学计量单位。
*/
get term(): number;
set term(val: number);
/**
* @en Range of the light.
* @zh 光源范围。
*/
get range(): number;
set range(val: number);
constructor();
protected _createLight(): void;
}
/**
* @en The ranged directional light component, Multiple ranged directional light sources are allowed in a scene.
* @zh 范围平行光光源组件，一个场景允许存在多个范围平行光光源。
*/
export class RangedDirectionalLight extends Light {
/**
* @en The light source intensity.
* @zh 光源强度。
*/
get illuminance(): number;
set illuminance(val: number);
constructor();
protected _createLight(): void;
}
/**
* @en The skinned mesh renderer component.
* @zh 蒙皮网格渲染器组件。
*/
export class SkinnedMeshRenderer extends MeshRenderer {
protected _skeleton: Skeleton | null;
protected _skinningRoot: Node | null;
protected _clip: AnimationClip | null;
/**
* @en The skeleton asset.
* @zh 骨骼资源。
*/
get skeleton(): Skeleton | null;
set skeleton(val: Skeleton | null);
/**
* @en The skinning root. (The node where the controlling Animation is located)
* @zh 骨骼根节点的引用，对应控制此模型的动画组件所在节点。
*/
get skinningRoot(): Node | null;
set skinningRoot(value: Node | null);
get model(): __private._cocos_3d_models_skinning_model__SkinningModel | __private._cocos_3d_models_baked_skinning_model__BakedSkinningModel | null;
/**
* Set associated animation.
* @internal This method only friends to skeletal animation component.
*/
associatedAnimation: SkeletalAnimation | null;
constructor();
onLoad(): void;
onDestroy(): void;
uploadAnimation(clip: AnimationClip | null): void;
/**
* Set if bake mode should be used.
* @internal This method only friends to skeletal animation component.
*/
setUseBakedAnimation(val?: boolean, force?: boolean): void;
setSharedMaterial(material: Material | null, index: number): void;
protected _updateModelParams(): void;
}
/**
* @en The skinned mesh batch renderer component, batches multiple skeleton-sharing [[SkinnedMeshRenderer]].
* @zh 蒙皮模型合批组件，用于合并绘制共享同一骨骼资源的所有蒙皮网格。
*/
export class SkinnedMeshBatchRenderer extends SkinnedMeshRenderer {
/**
* @en Size of the generated texture atlas.
* @zh 合图生成的最终图集的边长。
*/
atlasSize: number;
/**
* @en
* Texture properties that will be actually using the generated atlas.
* The first unit's texture will be used if not specified.
* @zh
* 材质中真正参与合图的贴图属性，不参与的属性统一使用第一个 unit 的贴图。
*/
batchableTextureNames: string[];
/**
* @en Source skinning model components, containing all the data to be batched.
* @zh 合批前的子蒙皮模型数组，最主要的数据来源。
*/
units: SkinnedMeshUnit[];
get mesh(): Mesh | null;
set mesh(val: Mesh | null);
get skeleton(): Skeleton | null;
set skeleton(val: Skeleton | null);
onLoad(): void;
onDestroy(): void;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
_onMaterialModified(idx: number, material: Material | null): void;
cook(): void;
cookMaterials(): void;
cookSkeletons(): void;
cookMeshes(): void;
protected cookTextures(target: Texture2D, prop: string, passIdx: number): void;
protected createTexture(prop: string): Texture2D;
protected resizeAtlases(): void;
}
export class SkinnedMeshUnit {
/**
* @en Skinned mesh of this unit.
* @zh 子蒙皮模型的网格模型。
*/
mesh: Mesh | null;
/**
* @en Skeleton of this unit.
* @zh 子蒙皮模型的骨骼。
*/
skeleton: Skeleton | null;
/**
* @en Skinning material of this unit.
* @zh 子蒙皮模型使用的材质。
*/
material: Material | null;
/**
* @en Local transform matrix
* @zh 本地变换矩阵
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
_localTransform: math.Mat4;
/**
* @en UV offset on texture atlas.
* @zh 在图集中的 uv 坐标偏移。
*/
set offset(offset: math.Vec2);
get offset(): math.Vec2;
/**
* @en UV extent on texture atlas.
* @zh 在图集中占的 UV 尺寸。
*/
set size(size: math.Vec2);
get size(): math.Vec2;
/**
* @en Convenient setter, copying all necessary information from target [[SkinnedMeshRenderer]] component.
* @zh 复制目标 [[SkinnedMeshRenderer]] 的所有属性到本单元，方便快速配置。
*/
set copyFrom(comp: SkinnedMeshRenderer | null);
get copyFrom(): SkinnedMeshRenderer | null;
}
export class LOD {
protected _screenUsagePercentage: number;
protected _renderers: MeshRenderer[];
constructor();
/**
* @en Minimum percentage of screen usage for the current lod in effect, range in [0, 1]
* @zh 本层级生效时，占用屏幕的最小百分比, 取值范围[0, 1]
*/
get screenUsagePercentage(): number;
set screenUsagePercentage(val: number);
/**
* @en Get the list of [[MeshRenderer]] used by the current lod.
* @zh 获取当前lod使用的 [[MeshRenderer]] 列表
*/
get renderers(): readonly MeshRenderer[];
/**
* @en reset _renderers to meshList or [], LODData's model will be reset too.
* @zh 重置 _renderers 为 meshList或空数组, LODData上的model也会被重置
*/
set renderers(meshList: readonly MeshRenderer[]);
/**
* @en Get the number of LOD.
* @zh 获取LOD的数量
*/
get rendererCount(): number;
/**
* @en Insert a [[MeshRenderer]] before specific index position.
* @zh 在指定的数组索引处插入一个[[MeshRenderer]]
* @param index @en The rendering array is indexed from 0. If - 1 is passed, it will be added to the end of the list.
* @zh renderers数组从0开始索引，若传递-1将会被添加到列表末尾。
* @param renderer @en The mesh-renderer object. @zh [[MeshRenderer]] 对象
* @returns @en The inserted [[MeshRenderer]] @zh 返回被插入的 [[MeshRenderer]] 对象
*/
insertRenderer(index: number, renderer: MeshRenderer): MeshRenderer;
/**
* @en Delete the [[MeshRenderer]] at specific index position.
* @zh 删除指定索引处的[[MeshRenderer]]
* @param index @en 0 indexed position in renderer array, when -1 is specified, the last element will be deleted.
* @zh _renderers从0开始索引，传递-1则最后一个元素会被删除。
* @returns @en The deleted [[MeshRenderer]], or null if the specified index does not exist. @zh 如果指定索引处的对象存在，返回被删除对象否则返回null。
*/
deleteRenderer(index: number): MeshRenderer | null;
/**
* @en Get the [[MeshRenderer]] at specific index position.
* @zh 获取指定索引处的[[MeshRenderer]]
* @param index @en Value range from 0 to _renderers's length. @zh 取值范围是[0, _renderers长度]
* @return @en Returns the [[MeshRenderer]] at the specified index, or null if the specified index does not exist. @zh 返回指定索引处的对象，若不存在则返回null。
*/
getRenderer(index: number): MeshRenderer | null;
/**
* @en Update the [[MeshRenderer]] at specific index position.
* @zh 更新指定索引处的 [[MeshRenderer]]
* @param index @en Value range from 0 to _renderers's length @zh 取值范围是 [0, _renderers数组长度]
*/
setRenderer(index: number, renderer: MeshRenderer): void;
}
export class LODGroup extends Component {
/**
* @en Object reference point in local space, e.g. center of the bound volume for all LODs
*/
protected _localBoundaryCenter: math.Vec3;
/**
* @en Object Size in local space, may be auto-calculated value from object bounding box or value from user input.
*/
protected _objectSize: number;
/**
*@en The array of LODs
*/
protected _LODs: LOD[];
constructor();
/**
* @en Obtain LOD level numbers.
* @zh 获取LOD层级数
*/
get lodCount(): number;
/**
* @en Set current AABB's size.
* @zh 设置当前包围盒的大小
*/
set objectSize(val: number);
/**
* @en Get current AABB's size.
* @zh 获取当前包围盒的大小
*/
get objectSize(): number;
/**
* @en Get LOD array config.
* @zh 获取 LOD 数组
*/
get LODs(): readonly LOD[];
/**
* @en Reset current LODs to new value.
* @ 重置 LODs 为当前新设置的值。
*/
set LODs(valArray: readonly LOD[]);
/**
* @en Insert the [[LOD]] at specific index position, [[LOD]] will be inserted to the last position if index less than 0 or greater than lodCount.
* @zh 在指定索引处插入 [[LOD]], 若索引为负或超过lodCount，则在末尾添加
* @param index @en location where lod is added. @zh lod被插入的位置
* @param screenUsagePercentage @en The minimum screen usage percentage that the currently set lod starts to use, range in[0, 1].
* @zh lod生效时的最低屏幕显示百分比要求，取值范围[0, 1]
* @param lod @en If this parameter is not set, it will be created by default. @zh 如果参数没传，则内部创建
* @returns @en The new lod added. @zh 返回被添加的lod
*/
insertLOD(index: number, screenUsagePercentage?: number, lod?: LOD): LOD;
/**
* @en Erase the [[LOD]] at specific index position.
* @zh 删除指定索引处的 [[LOD]]
* @param index @en Index of the erased lod, range in [0, lodCount]. @zh 被删除对象索引, 取值范围[0, lodCount]
* @returns @en Erased lod. @zh 被删除的对象
*/
eraseLOD(index: number): LOD | null;
/**
* @en Get [[LOD]] at specific index position.
* @zh 获取指定索引处的 [[LOD]]
* @param index @en Range in [0, lodCount]. @zh 取值范围[0, lodCount]
* @returns @en Lod at specified index, or null. @zh 返回指定索引的lod或null
*/
getLOD(index: number): LOD | null;
/**
* @en Update the [[LOD]] at specific index position.
* @zh 更新指定索引处的 [[LOD]]
* @param index, update lod at specified index.
* @param lod, the updated lod.
*/
setLOD(index: number, lod: LOD): void;
/**
* @en Recalculate the bounding box, and the interface will recalculate the localBoundaryCenter and objectSize
* @zh 重新计算包围盒，该接口会更新 localBoundaryCenter 和 objectSize
*/
recalculateBounds(): void;
/**
* @en reset current objectSize to 1, and recalculate screenUsagePercentage.
* @zh 重置 objectSize 的大小为1，该接口会重新计算 screenUsagePercentage
*/
resetObjectSize(): void;
/**
* @zh 强制使用某一级的LOD
* @en Force LOD level to use.
* lodLevel @en The LOD level to use. Passing lodLevel < 0 will return to standard LOD processing. @zh 要使用的LOD层级，为负数时使用标准的处理流程
*/
forceLOD(lodLevel: number): void;
/**
* @en Force multi LOD level to use, This function is only called in editor.
* @zh 强制使用某几级的LOD,该接口只会在编辑器下调用。
* lodIndexArray @en The LOD level array. Passing [] will return to standard LOD processing. @zh 要使用的LOD层级数组，传[]时将使用标准的处理流程。
*/
forceLODs(lodIndexArray: number[]): void;
onLoad(): void;
_onRemove(comp: Component): void;
onRestore(): void;
onEnable(): void;
onDisable(): void;
}
export class ReflectionProbe extends Component {
protected static readonly DEFAULT_CUBE_SIZE: Readonly;
protected static readonly DEFAULT_PLANER_SIZE: Readonly;
protected readonly _lastSize: math.Vec3;
protected _resolution: number;
protected _clearFlag: renderer.scene.ProbeClearFlag;
protected _backgroundColor: math.Color;
protected _visibility: number;
protected _probeType: renderer.scene.ProbeType;
protected _cubemap: TextureCube | null;
protected readonly _size: math.Vec3;
protected _sourceCamera: Camera | null;
protected _probe: renderer.scene.ReflectionProbe | null;
protected _previewSphere: Node | null;
protected _previewPlane: Node | null;
/**
* @en
* Gets or sets the size of the box
* @zh
* 获取或设置包围盒的大小。
*/
set size(value: math.Vec3);
get size(): math.Vec3;
/**
* @en Environment reflection or plane reflection.
* @zh 设置探针类型，环境反射或者平面反射
*/
set probeType(value: renderer.scene.ProbeType);
get probeType(): renderer.scene.ProbeType;
/**
* @en set render texture size
* @zh 设置渲染纹理大小
*/
set resolution(value: number);
get resolution(): number;
/**
* @en Clearing flags of the camera, specifies which part of the framebuffer will be actually cleared every frame.
* @zh 相机的缓冲清除标志位，指定帧缓冲的哪部分要每帧清除。
*/
set clearFlag(value: number);
get clearFlag(): number;
/**
* @en Clearing color of the camera.
* @zh 相机的颜色缓冲默认值。
*/
set backgroundColor(val: math.Color);
get backgroundColor(): math.Color;
/**
* @en Visibility mask, declaring a set of node layers that will be visible to this camera.
* @zh 可见性掩码，声明在当前相机中可见的节点层级集合。
*/
get visibility(): number;
set visibility(val: number);
/**
* @en The camera to render planar reflections, specified by the user
* @zh 需要渲染平面反射的相机，由用户指定
*/
set sourceCamera(camera: Camera);
get sourceCamera(): Camera;
/**
* @en fast bake no convolution.
* @zh 快速烘焙不会进行卷积。
*/
get fastBake(): boolean;
set fastBake(val: boolean);
set cubemap(val: TextureCube | null);
get cubemap(): TextureCube | null;
get probe(): renderer.scene.ReflectionProbe;
/**
* @en Reflection probe cube mode preview sphere
* @zh 反射探针cube模式的预览小球
*/
set previewSphere(val: Node | null);
get previewSphere(): Node | null;
/**
* @en Reflection probe planar mode preview plane
* @zh 反射探针Planar模式的预览平面
*/
set previewPlane(val: Node);
get previewPlane(): Node;
onLoad(): void;
onEnable(): void;
onDisable(): void;
start(): void;
onDestroy(): void;
update(dt: number): void;
/**
* @en Clear the baked cubemap.
* @zh 清除烘焙的cubemap
*/
clearBakedCubemap(): void;
}
/**
* @en Use Reflection probe
* @zh 使用反射探针。
*/
export enum ReflectionProbeType {
/**
* @en Use the default skybox.
* @zh 使用默认天空盒。
*/
NONE = 0,
/**
* @en Cubemap generate by probe.
* @zh Probe烘焙的cubemap。
*/
BAKED_CUBEMAP = 1,
/**
* @en Realtime planar reflection.
* @zh 实时平面反射。
*/
PLANAR_REFLECTION = 2,
/**
* @en Mixing between reflection probe.
* @zh 反射探针之间进行混合。
*/
BLEND_PROBES = 3,
/**
* @en Mixing between reflection probe and skybox.
* @zh 反射探针之间混合或反射探针和天空盒之间混合。
*/
BLEND_PROBES_AND_SKYBOX = 4
}
/**
* @zh 动画剪辑表示一段使用动画编辑器编辑的关键帧动画或是外部美术工具生产的骨骼动画。
* 它的数据主要被分为几层：轨道、关键帧和曲线。
* @en The animation clip represents a sequence of key frame animation created with the animation editor or skeletal animation other DCC tools.
* The data is divided in different levels: tracks, key frames, curves.
*/
export class AnimationClip extends Asset {
static WrapMode: typeof __private._cocos_animation_types__WrapMode;
/**
* @en Crate clip with a set of sprite frames
* @zh 使用一组序列帧图片来创建动画剪辑
* @example
* ```
* import { AnimationClip } from 'cc';
* const clip = AnimationClip.createWithSpriteFrames(spriteFrames, 10);
* ```
*/
static createWithSpriteFrames(spriteFrames: SpriteFrame[], sample: number): AnimationClip;
/**
* @zh 动画帧率，单位为帧/秒。注意此属性仅用于编辑器动画编辑。
* @en Animation frame rate: frames per second.
* Note this property is only used for animation editing in Editor.
*/
sample: number;
/**
* @zh 动画的播放速度。
* @en Animation playback speed.
*/
speed: number;
/**
* @zh 动画的循环模式。
* @en Animation loop mode.
*/
wrapMode: __private._cocos_animation_types__WrapMode;
/**
* Sets if node TRS curves in this animation can be blended.
* Normally this flag is enabled for model animation and disabled for other case.
* @internal This is an internal slot. Never use it in your code.
*/
enableTrsBlending: boolean;
/**
* @zh 动画的周期。
* @en Animation duration.
*/
get duration(): number;
set duration(value: number);
/**
* @en
* Gets the count of tracks this animation owns.
* @zh
* 获取此动画中的轨道数量。
*/
get tracksCount(): number;
/**
* @en
* Gets an iterable to tracks.
* @zh
* 获取可用于迭代轨道的对象。
*/
get tracks(): Iterable;
get hash(): number;
/**
* @zh 动画包含的事件数据。
* @en Associated event data.
*/
get events(): AnimationClip.IEvent[];
set events(value: AnimationClip.IEvent[]);
get [exoticAnimationTag](): ExoticAnimation | null;
set [exoticAnimationTag](value: ExoticAnimation | null);
/**
* Gets if this animation clip contains additive animation.
* @experimental
*/
get isAdditive_experimental(): boolean;
/**
* Accesses the additive animation settings.
* @internal
*/
get [additiveSettingsTag](): AnimationClipAdditiveSettings;
onLoaded(): void;
/**
* @en
* Counts the time range that the tracks within this animation span.
* @zh
* 获取此动画所有轨道占据的时间范围。
* @returns The time range.
*/
range(): __private._cocos_animation_tracks_utils__Range;
/**
* @en
* Gets the specified track.
* @zh
* 获取指定的轨道。
* @param index Index to the track.
* @returns The track.
*/
getTrack(index: number): animation.Track;
/**
* @en
* Adds a track into this animation.
* @zh
* 添加一个轨道到此动画中。
* @param track The track.
* @returns Index to the track.
*/
addTrack(track: animation.Track): number;
/**
* @en
* Removes a track from this animation.
* @zh
* 移除此动画中的指定轨道。
* @param index Index to the track.
*/
removeTrack(index: number): void;
/**
* @en
* Removes all tracks from this animation.
* @zh
* 移除此动画的所有轨道。
*/
clearTracks(): void;
/**
* Returns if this clip has any event.
* @internal Do not use this in your code.
*/
containsAnyEvent(): boolean;
/**
* Creates an event evaluator for this animation.
* @param targetNode Target node used to fire events.
* @internal Do not use this in your code.
*/
createEventEvaluator(targetNode: Node): __private._cocos_animation_animation_clip__EventEvaluator;
/**
* Returns if this clip has any embedded player.
* @internal Do not use this in your code.
*/
containsAnyEmbeddedPlayer(): boolean;
/**
* Creates an embedded player evaluator for this animation.
* @param targetNode Target node.
* @internal Do not use this in your code.
*/
createEmbeddedPlayerEvaluator(targetNode: Node): __private._cocos_animation_animation_clip__EmbeddedPlayerEvaluation;
/**
* Creates an evaluator for this animation.
* @param context The context.
* @returns The evaluator.
* @internal Do not use this in your code.
*/
createEvaluator(context: __private._cocos_animation_animation_clip__AnimationClipEvalContext): __private._cocos_animation_animation_clip__AnimationClipEvaluation;
destroy(): boolean;
[__private._cocos_animation_internal_symbols__BAKE_SKELETON_CURVE_SYMBOL](start: number, samples: number, frames: number): __private._cocos_animation_animation_clip__SkeletonAnimationBakeInfo;
/**
* Convert all untyped tracks into typed ones and delete the original.
* @param refine How to decide the type on specified path.
* @internal DO NOT USE THIS IN YOUR CODE.
*/
upgradeUntypedTracks(refine: __private._cocos_animation_tracks_untyped_track__UntypedTrackRefine): void;
/**
* @internal Export for test.
*/
[__private._cocos_animation_animation_clip__searchForRootBonePathSymbol](): string;
/**
* @zh 曲线可引用的所有时间轴。
* @en Frame keys referenced by curves.
* @deprecated Since V3.3. Please reference to the track/channel/curve mechanism introduced in V3.3.
*/
get keys(): number[][];
set keys(value: number[][]);
/**
* @zh 此动画包含的所有曲线。
* @en Curves this animation contains.
* @deprecated Since V3.3. Please reference to the track/channel/curve mechanism introduced in V3.3.
*/
get curves(): AnimationClip._legacy.LegacyClipCurve[];
set curves(value: AnimationClip._legacy.LegacyClipCurve[]);
/**
* @deprecated Since V3.3. Please reference to the track/channel/curve mechanism introduced in V3.3.
*/
get commonTargets(): AnimationClip._legacy.LegacyCommonTarget[];
set commonTargets(value: AnimationClip._legacy.LegacyCommonTarget[]);
/**
* @en
* The animation's data.
* @zh
* 此动画的数据。
* @deprecated Since V3.3. Please reference to the track/channel/curve mechanism introduced in V3.3.
*/
get data(): Uint8Array | null;
/**
* @deprecated Since V3.3. Please reference to the track/channel/curve mechanism introduced in V3.3.
*/
getPropertyCurves(): readonly AnimationClip._legacy.LegacyRuntimeCurve[];
/**
* @deprecated Since V3.3. Please reference to the track/channel/curve mechanism introduced in V3.3.
*/
get eventGroups(): readonly __private._cocos_animation_animation_clip__IAnimationEventGroup[];
/**
* @zh 提交事件数据的修改。
* 当你修改了 `this.events` 时，必须调用 `this.updateEventDatas()` 使修改生效。
* @en
* Commit event data update.
* You should call this function after you changed the `events` data to take effect.
* @deprecated Since V3.3. Please Assign to `this.events`.
*/
updateEventDatas(): void;
/**
* @zh 返回本动画是否包含事件数据。
* @en Returns if this animation contains event data.
* @protected
*/
hasEvents(): boolean;
/**
* Migrates legacy data into tracks.
* NOTE: This method tend to be used as internal purpose or patch.
* DO NOT use it in your code since it might be removed for the future at any time.
* @internal Since V3.3. Please reference to the track/channel/curve mechanism introduced in V3.3.
*/
syncLegacyData(): void;
/**
* @internal
*/
get [embeddedPlayerCountTag](): number;
/**
* @internal
*/
[getEmbeddedPlayersTag](): Iterable;
/**
* @internal
*/
[addEmbeddedPlayerTag](embeddedPlayer: EmbeddedPlayer): void;
/**
* @internal
*/
[removeEmbeddedPlayerTag](embeddedPlayer: EmbeddedPlayer): void;
/**
* @internal
*/
[clearEmbeddedPlayersTag](): void;
/**
* @zh 获取此动画剪辑中的辅助曲线数量。
* @en Gets the count of auxiliary curves within this animation clip.
*/
get auxiliaryCurveCount_experimental(): number;
/**
* @zh 返回此动画剪辑中所有辅助曲线的名称。
* @en Returns names of all auxiliary curves within this animation clip.
*/
getAuxiliaryCurveNames_experimental(): readonly string[];
/**
* @zh 返回此动画剪辑中是否存在指定的辅助曲线。
* @en Returns if the specified auxiliary curve exists in this animation clip.
*/
hasAuxiliaryCurve_experimental(name: string): boolean;
/**
* @zh 添加一条辅助曲线。如果已存在同名的辅助曲线，则直接返回。
* @en Adds an auxiliary curve. Directly return if there is already such named auxiliary curve.
* @param name @zh 辅助曲线的名称。@en The auxiliary curve's name.
* @returns @zh 新增或已存在的辅助曲线。 @en The newly created or existing auxiliary curve.
* @experimental
*/
addAuxiliaryCurve_experimental(name: string): RealCurve;
/**
* @zh 获取指定的辅助曲线。
* @en Gets the specified auxiliary curve.
* @param name @zh 辅助曲线的名称。@en The auxiliary curve's name.
* @returns @zh 指定的辅助曲线。@en The specified auxiliary curve.
* @experimental
*/
getAuxiliaryCurve_experimental(name: string): RealCurve;
/**
* @zh 重命名指定的辅助曲线。
* @en Renames the specified auxiliary curve.
* @param name @zh 要重命名的辅助曲线的名称。@en Name of the auxiliary curve to rename.
* @param newName @zh 新名称。@en New name.
*/
renameAuxiliaryCurve_experimental(name: string, newName: string): void;
/**
* @zh 移除指定的辅助曲线。
* @en Removes the specified auxiliary curve.
* @param name @zh 辅助曲线的名称。@en The auxiliary curve's name.
* @experimental
*/
removeAuxiliaryCurve_experimental(name: string): void;
/**
* @internal
*/
_trySyncLegacyData(): void;
}
export namespace AnimationClip {
export interface IEvent {
frame: number;
func: string;
params: string[];
}
export namespace _legacy {
export class AnimationClipLegacyData {
constructor(duration: number);
get keys(): number[][];
set keys(value: number[][]);
get curves(): LegacyClipCurve[];
set curves(value: LegacyClipCurve[]);
get commonTargets(): LegacyCommonTarget[];
set commonTargets(value: LegacyCommonTarget[]);
/**
* 此动画的数据。
*/
get data(): Uint8Array | null;
getPropertyCurves(): readonly LegacyRuntimeCurve[];
toTracks(): animation.Track[];
protected _createPropertyCurves(): void;
}
/**
* Legacy curve uses time based bezier curve interpolation.
* That's, interpolate time 'x'(time ratio between two frames, eg.[0, 1])
* and then use the interpolated time to sample curve.
* Now we need to compute the the end tangent of previous frame and the start tangent of the next frame.
* @param timeBezierPoints Bezier points used for legacy time interpolation.
* @param previousTime Time of the previous keyframe.
* @param previousValue Value of the previous keyframe.
* @param nextTime Time of the next keyframe.
* @param nextValue Value of the next keyframe.
*/
export function timeBezierToTangents(timeBezierPoints: BezierControlPoints, previousTime: number, previousKeyframe: RealKeyframeValue, nextTime: number, nextKeyframe: RealKeyframeValue): void;
/**
* 表示曲线值，曲线值可以是任意类型，但必须符合插值方式的要求。
*/
export type LegacyCurveValue = any;
/**
* 表示曲线的目标对象。
*/
export type LegacyCurveTarget = Record;
/**
* 内置帧时间渐变方式名称。
*/
export type LegacyEasingMethodName = keyof (typeof easing);
/**
* 帧时间渐变方式。可能为内置帧时间渐变方式的名称或贝塞尔控制点。
*/
export type LegacyEasingMethod = LegacyEasingMethodName | BezierControlPoints;
export type LegacyCompressedEasingMethods = Record;
export type LegacyLerpFunction = (from: T, to: T, t: number, dt: number) => T;
export interface LegacyClipCurveData {
/**
* 曲线使用的时间轴。
* @see {AnimationClip.keys}
*/
keys: number;
/**
* 曲线值。曲线值的数量应和 `keys` 所引用时间轴的帧数相同。
*/
values: LegacyCurveValue[];
/**
* 曲线任意两帧时间的渐变方式。仅当 `easingMethods === undefined` 时本字段才生效。
*/
easingMethod?: LegacyEasingMethod;
/**
* 描述了每一帧时间到下一帧时间之间的渐变方式。
*/
easingMethods?: LegacyEasingMethod[] | LegacyCompressedEasingMethods;
/**
* 是否进行插值。
* @default true
*/
interpolate?: boolean;
/**
* For internal usage only.
*/
_arrayLength?: number;
}
export interface LegacyClipCurve {
commonTarget?: number;
modifiers: animation.TargetPath[];
valueAdapter?: animation.IValueProxyFactory;
data: LegacyClipCurveData;
}
export interface LegacyCommonTarget {
modifiers: animation.TargetPath[];
valueAdapter?: animation.IValueProxyFactory;
}
export type LegacyMaybeCompactCurve = Omit & {
data: Omit & {
values: any[] | CompactValueTypeArray;
};
};
export type LegacyMaybeCompactKeys = Array;
export type LegacyRuntimeCurve = Pick & {
/**
* 属性曲线。
*/
curve: AnimCurve;
/**
* 曲线采样器。
*/
sampler: RatioSampler | null;
};
export interface LegacyObjectCurveData {
[propertyName: string]: LegacyClipCurveData;
}
export interface LegacyComponentsCurveData {
[componentName: string]: LegacyObjectCurveData;
}
export interface LegacyNodeCurveData {
props?: LegacyObjectCurveData;
comps?: LegacyComponentsCurveData;
}
}
export type WrapMode = __private._cocos_animation_animation_clip__WrapMode_;
}
/**
* @en
* The AnimationState gives full control over animation playback process.
* In most cases the Animation Component is sufficient and easier to use. Use the AnimationState if you need full control.
* @zh
* AnimationState 完全控制动画播放过程。
* 大多数情况下 动画组件 是足够和易于使用的。如果您需要更多的动画控制接口，请使用 AnimationState。
*
*/
export class AnimationState extends __private._cocos_animation_playable__Playable {
/**
* @en The clip that is being played by this animation state.
* @zh 此动画状态正在播放的剪辑。
*/
get clip(): AnimationClip;
/**
* @en The name of the playing animation.
* @zh 动画的名字。
*/
get name(): string;
get length(): number;
/**
* @en
* Wrapping mode of the playing animation.
* Notice : dynamic change wrapMode will reset time and repeatCount property
* @zh
* 动画循环方式。
* 需要注意的是，动态修改 wrapMode 时，会重置 time 以及 repeatCount。
* @default: WrapMode.Normal
*/
get wrapMode(): __private._cocos_animation_types__WrapMode;
set wrapMode(value: __private._cocos_animation_types__WrapMode);
/**
* @en The animation's iteration count property.
*
* A real number greater than or equal to zero (including positive infinity) representing the number of times
* to repeat the animation node.
*
* Values less than zero and NaN values are treated as the value 1.0 for the purpose of timing model
* calculations.
*
* @zh 迭代次数，指动画播放多少次后结束, normalize time。 如 2.5（2次半）。
*
* @default 1
*/
get repeatCount(): number;
set repeatCount(value: number);
/**
* @en The start delay which represents the number of seconds from an animation's start time to the start of
* the active interval.
* @zh 延迟多少秒播放。
* @default 0
*/
get delay(): number;
set delay(value: number);
/**
* @en The iteration duration of this animation in seconds. (length)
* @zh 单次动画的持续时间，秒。（动画长度）
* @readOnly
*/
duration: number;
/**
* @en
* Gets or sets the playback range.
* The `min` and `max` field of the range are measured in seconds.
* While setting, the range object should be a valid range.
* The actual playback range would be the inclusion of this field and [0, duration].
* Set this field would reset the accumulated play time.
* If `min === max`, the animation always play at `min`.
* @zh
* 获取或设置播放范围。
* 范围的 `min`、`max` 字段都是以秒为单位的。
* 设置时，应当指定一个有效的范围；实际的播放范围是该字段和 [0, 周期] 之间的交集。
* 设置播放范围时将重置累计播放时间。
* 如果 `min === max`，该动画将一直在 `min` 处播放。
*/
get playbackRange(): Readonly<{
min: number;
max: number;
}>;
set playbackRange(value: Readonly<{
min: number;
max: number;
}>);
/**
* @en The animation's playback speed. 1 is normal playback speed.
* @zh 播放速率。
* @default: 1.0
*/
get speed(): number;
set speed(value: number);
/**
* @en The current accumulated time of this animation in seconds.
* @zh 动画当前**累计播放**的时间，单位为秒。
* @default 0
*/
time: number;
/**
* @en Gets the time progress, in seconds.
* @zh 获取动画的时间进度，单位为秒。
*/
get current(): number;
/**
* @en Gets the playback ratio.
* @zh 获取动画播放的比例时间。
*/
get ratio(): number;
/**
* @en
* The weight of this animation state.
* @zh
* 此动画状态的权重。
*/
get weight(): number;
set weight(value: number);
frameRate: number;
/**
* @internal This field is only visible from within internal.
*/
protected _targetNode: Node | null;
/**
* @internal This field is only visible from within internal.
*/
protected _curveLoaded: boolean;
/**
* @internal For internal usage. Really hack...
*/
protected _doNotCreateEval: boolean;
constructor(clip: AnimationClip, name?: string);
/**
* This method is used for internal purpose only.
*/
get curveLoaded(): boolean;
initialize(root: Node, blendStateBuffer?: __private._cocos_3d_skeletal_animation_skeletal_animation_blending__BlendStateBuffer, mask?: AnimationMask): void;
destroy(): void;
/**
* @deprecated Since V1.1.1, animation states were no longer defined as event targets.
* To process animation events, use `Animation` instead.
*/
emit(...args: any[]): void;
/**
* @deprecated Since V1.1.1, animation states were no longer defined as event targets.
* To process animation events, use `Animation` instead.
*/
on(type: string, callback: Function, target?: any): void | null;
/**
* @deprecated Since V1.1.1, animation states were no longer defined as event targets.
* To process animation events, use `Animation` instead.
*/
once(type: string, callback: Function, target?: any): void | null;
/**
* @deprecated Since V1.1.1, animation states were no longer defined as event targets.
* To process animation events, use `Animation` instead.
*/
off(type: string, callback: Function, target?: any): void;
/**
* @zh
* 是否允许触发 `LastFrame` 事件。
* 该方法仅用作内部用途。
* @en
* Whether `LastFrame` should be triggered.
* @param allowed True if the last frame events may be triggered.
* This method is only used for internal purpose only.
*/
allowLastFrameEvent(allowed: boolean): void;
/**
* This method is used for internal purpose only.
* @internal
*/
_setEventTarget(target: any): void;
setTime(time: number): void;
update(delta: number): void;
sample(): __private._cocos_animation_types__WrappedInfo;
protected onPlay(): void;
protected onStop(): void;
protected onResume(): void;
protected onPause(): void;
/**
* @internal
*/
protected _sampleCurves(time: number): void;
}
/**
* @en
* Animation component governs a group of animation states to control playback of the states.
* For convenient, it stores a group of animation clips.
* Each of those clips would have an associated animation state uniquely created.
* Animation component is eventful, it dispatch a serials playback status events.
* See [[EventType]].
* @zh
* 动画组件管理一组动画状态，控制它们的播放。
* 为了方便，动画组件还存储了一组动画剪辑。
* 每个剪辑都会独自创建一个关联的动画状态对象。
* 动画组件具有事件特性，它会派发一系列播放状态相关的事件。
* 参考 [[EventType]]
*/
export class Animation extends __private._cocos_animation_animation_component__Animation_base {
/**
* @en
* Gets or sets clips this component governs.
* When set, associated animation state of each existing clip will be stopped.
* If the existing default clip is not in the set of new clips, default clip will be reset to null.
* @zh
* 获取或设置此组件管理的剪辑。
* 设置时，已有剪辑关联的动画状态将被停止；若默认剪辑不在新的动画剪辑中，将被重置为空。
*/
get clips(): (AnimationClip | null)[];
set clips(value: (AnimationClip | null)[]);
/**
* @en
* Gets or sets the default clip.
* Two clips that both have same non-empty UUID are treat as equivalent.
* @zh
* 获取或设置默认剪辑。
* 设置时，若指定的剪辑不在 `this.clips` 中则会被自动添加至 `this.clips`。
* 具有相同的非空 UUID 的两个动画剪辑将被视为是相同的。
* @see [[playOnLoad]]
*/
get defaultClip(): AnimationClip | null;
set defaultClip(value: AnimationClip | null);
static EventType: typeof __private._cocos_animation_animation_state__EventType;
/**
* @en
* Whether the default clip should get into playing when this components starts.
* Note, this field takes no effect if `crossFade()` or `play()` has been called before this component starts.
* @zh
* 是否在组件开始运行时自动播放默认剪辑。
* 注意，若在组件开始运行前调用了 `crossFade` 或 `play()`，此字段将不会生效。
*/
playOnLoad: boolean;
/**
* @internal
*/
protected _crossFade: __private._cocos_animation_cross_fade__CrossFade;
/**
* @internal
*/
protected _nameToState: Record;
/**
* @internal
*/
protected _clips: (AnimationClip | null)[];
/**
* @internal
*/
protected _defaultClip: AnimationClip | null;
onLoad(): void;
start(): void;
onEnable(): void;
onDisable(): void;
onDestroy(): void;
/**
* @en
* Switch to play specified animation state, without fading.
* @zh
* 立即切换到指定动画状态。
* @param name The name of the animation to be played, if absent, the default clip will be played
*/
play(name?: string): void;
/**
* @en
* Smoothly switch to play specified animation state.
* @zh
* 平滑地切换到指定动画状态。
* @param name The name of the animation to switch to
* @param duration The duration of the cross fade, default value is 0.3s
*/
crossFade(name: string, duration?: number): void;
/**
* @en
* Pause all animation states and all switching.
* @zh
* 暂停所有动画状态，并暂停所有切换。
*/
pause(): void;
/**
* @en
* Resume all animation states and all switching.
* @zh
* 恢复所有动画状态，并恢复所有切换。
*/
resume(): void;
/**
* @en
* Stop all animation states and all switching.
* @zh
* 停止所有动画状态，并停止所有切换。
*/
stop(): void;
/**
* @en
* Get specified animation state.
* @zh
* 获取指定的动画状态。
* @param name The name of the animation
* @returns If no animation found, return null, otherwise the correspond animation state is returned
*/
getState(name: string): AnimationState;
/**
* @en
* Creates a state for specified clip.
* If there is already a clip with same name, the existing animation state will be stopped and overridden.
* @zh
* 使用指定的动画剪辑创建一个动画状态。
* 若指定名称的动画状态已存在，已存在的动画状态将先被设为停止并被覆盖。
* @param clip The animation clip
* @param name The animation state name, if absent, the default clip's name will be used
* @returns The animation state created
*/
createState(clip: AnimationClip, name?: string): AnimationState;
/**
* @en
* Stops and removes specified clip.
* @zh
* 停止并移除指定的动画状态。
* @param name The name of the animation state
*/
removeState(name: string): void;
/**
* @zh
* 添加一个动画剪辑到 `this.clips`中并以此剪辑创建动画状态。
* @en
* Adds an animation clip into this component and creates a animation state for this clip.
* @param clip The animation clip
* @param name The animation state name, if absent, the default clip's name will be used
* @returns The created animation state
*/
addClip(clip: AnimationClip, name?: string): AnimationState;
/**
* @en
* Remove clip from the animation list. This will remove the clip and any animation states based on it.
* If there are animation states depend on the clip are playing or clip is defaultClip, it will not delete the clip.
* But if force is true, then will always remove the clip and any animation states based on it. If clip is defaultClip,
* defaultClip will be reset to null
* @zh
* 从动画列表中移除指定的动画剪辑，
* 如果依赖于 clip 的 AnimationState 正在播放或者 clip 是 defaultClip 的话，默认是不会删除 clip 的。
* 但是如果 force 参数为 true，则会强制停止该动画，然后移除该动画剪辑和相关的动画。这时候如果 clip 是 defaultClip，defaultClip 将会被重置为 null。
* @param force - If force is true, then will always remove the clip and any animation states based on it.
*/
removeClip(clip: AnimationClip, force?: boolean): void;
/**
* @en
* Register animation event callback.
* The event arguments will provide the AnimationState which emit the event.
* When play an animation, will auto register the event callback to the AnimationState,
* and unregister the event callback from the AnimationState when animation stopped.
* @zh
* 注册动画事件回调。
* 回调的事件里将会附上发送事件的 AnimationState。
* 当播放一个动画时，会自动将事件注册到对应的 AnimationState 上，停止播放时会将事件从这个 AnimationState 上取消注册。
* @param type The event type to listen to
* @param callback The callback when event triggered
* @param target The callee when invoke the callback, could be absent
* @return The registered callback
* @example
* ```ts
* onPlay: function (type, state) {
* // callback
* }
*
* // register event to all animation
* animation.on('play', this.onPlay, this);
* ```
*/
on void>(type: __private._cocos_animation_animation_state__EventType, callback: TFunction, thisArg?: any, once?: boolean): TFunction;
once void>(type: __private._cocos_animation_animation_state__EventType, callback: TFunction, thisArg?: any): TFunction;
/**
* @en
* Unregister animation event callback.
* @zh
* 取消注册动画事件回调。
* @param {String} type The event type to unregister
* @param {Function} callback The callback to unregister
* @param {Object} target The callee of the callback, could be absent
* @example
* ```ts
* // unregister event to all animation
* animation.off('play', this.onPlay, this);
* ```
*/
off(type: __private._cocos_animation_animation_state__EventType, callback?: (...any: any[]) => void, thisArg?: any): void;
/**
* @internal
*/
protected _createState(clip: AnimationClip, name?: string): AnimationState;
/**
* @internal
*/
protected _doCreateState(clip: AnimationClip, name: string): AnimationState;
/**
* @internal This method only friends to skeletal animation component.
*/
protected doPlayOrCrossFade(state: AnimationState, duration: number): void;
}
export namespace Animation {
export type EventType = __private._cocos_animation_animation_component__EventType_;
}
export namespace animation {
/**
* @en
* Represents variable's value.
* @zh
* 表示变量的值。
*/
export type Value_experimental = Value | Readonly | Readonly;
/**
* @en
* Represents animation graph variable types.
* @zh
* 表示动画图变量的类型。
*/
export enum VariableType {
/**
* @en
* A floating.
* @zh
* 浮点数。
*/
FLOAT = 0,
/**
* @en
* A boolean.
* @zh
* 布尔值。
*/
BOOLEAN = 1,
/**
* @en
* A trigger.
* @zh
* 触发器。
*/
TRIGGER = 2,
/**
* @en
* An integer.
* @zh
* 整数。
*/
INTEGER = 3,
/**
* @zh
* 三维向量。
* @en
* Vector 3d.
*/
VEC3_experimental = 4,
/**
* @zh
* 四元数。
* @en
* Quaternion.
*/
QUAT_experimental = 5
}
/**
* @en
* Value proxy factory for setting uniform on material target.
* @zh
* 用于设置材质目标上指定 Uniform 的曲线值代理工厂。
*/
export class UniformProxyFactory implements IValueProxyFactory {
/**
* @en Pass index.
* @zh Pass 索引。
*/
passIndex: number;
/**
* @en Uniform name.
* @zh Uniform 名称。
*/
uniformName: string;
/**
* @en
* Specify the aimed channel of the uniform.
* Use this when you're aiming at a single channel of the uniform instead of who uniform.
* For example, only green(1) channel of a color uniform.
* @zh
* 指定目标 Uniform 的通道。
* 当你希望设置 Uniform 单独的通道而非整个 Uniform 时应该当使用此字段。
* 例如，仅设置颜色 Uniform 的红色通道。
*/
channelIndex: number | undefined;
constructor(uniformName?: string, passIndex?: number);
forTarget(target: unknown): IValueProxy | undefined;
}
/**
* @en
* Value proxy factory for setting morph weights of specified sub-mesh on model component target.
* @zh
* 用于设置模型组件目标上指定子网格的指定形状的形变权重的曲线值代理工厂。
*/
export class MorphWeightValueProxy implements IValueProxyFactory {
/**
* @en Sub mesh index.
* @zh 子网格索引。
*/
subMeshIndex: number;
/**
* @en Shape Index.
* @zh 形状索引。
*/
shapeIndex: number;
forTarget(target: MeshRenderer): {
set: (value: number) => void;
};
}
/**
* @en
* Value proxy factory for setting morph weights of specified sub-mesh on model component target.
* @zh
* 用于设置模型组件目标上指定子网格形变权重的曲线值代理工厂。
*/
export class MorphWeightsValueProxy implements IValueProxyFactory {
/**
* @en Sub-mesh index.
* @zh 子网格索引。
*/
subMeshIndex: number;
forTarget(target: MeshRenderer): {
set: (value: number[]) => void;
};
}
/**
* @en
* Value proxy factory for setting morph weights of each sub-mesh on model component target.
* @zh
* 用于设置模型组件目标上所有子网格形变权重的曲线值代理工厂。
*/
export class MorphWeightsAllValueProxy implements IValueProxyFactory {
forTarget(target: MeshRenderer): {
set: (value: number[]) => void;
};
}
/**
* @en
* A track describes how to trace the target and how to animate it.
* It's the basic unit of animation clip.
* @zh
* 轨道描述了动画目标的路径和动画的方式。它是动画剪辑的基础单元。
*/
export abstract class Track {
/**
* @en Track path.
* @zh 轨道路径。
*/
get path(): Readonly;
set path(value: Readonly);
/**
* @en Value proxy for the target.
* @zh 目标的值代理。
*/
get proxy(): IValueProxyFactory | undefined;
set proxy(value: IValueProxyFactory | undefined);
/**
* @internal
*/
get [__private._cocos_animation_tracks_track__trackBindingTag](): __private._cocos_animation_tracks_track__TrackBinding;
/**
* @en Channels on this track.
* @zh 此轨道上的通道。
* @returns Iterator to the channels.
*/
channels(): Iterable<__private._cocos_animation_tracks_track__Channel>;
/**
* @en Time range of this track.
* @zh 此轨道的时间范围。
* @returns The time range.
*/
range(): __private._cocos_animation_tracks_utils__Range;
/**
* @internal
*/
abstract [__private._cocos_animation_define__createEvalSymbol](): __private._cocos_animation_tracks_track__TrackEval;
}
/**
* @en Describes how to find the animation target.
* @zh 描述怎样寻址动画目标。
*/
export class TrackPath {
/**
* @en The length of the path.
* @zh 此路径的段数。
*/
get length(): number;
/**
* @en Appends a property path.
* @zh 附加一段属性路径。
* @param name The property's name.
* @returns `this`
*/
toProperty(name: string): TrackPath;
/**
* @en Appends an array element path.
* @zh 附加一段数组元素路径。
* @param index The element's index.
* @returns `this`
*/
toElement(index: number): TrackPath;
/**
* @en Appends a hierarchy path.
* @zh 附加一段层级路径。
* @param nodePath Path to the children.
* @returns `this`
*/
toHierarchy(nodePath: string): TrackPath;
/**
* @en Appends a component path.
* @zh 附加一段组件路径。
* @param constructor @en The constructor of the component. @zh 组件的构造函数。
* @returns `this`
*/
toComponent(constructor: __private.__types_globals__Constructor | string): TrackPath;
/**
* @internal Reserved for backward compatibility. DO NOT USE IT IN YOUR CODE.
*/
toCustomized(resolver: __private._cocos_animation_tracks_track__CustomizedTrackPathResolver): TrackPath;
/**
* @en Appends paths to this path.
* @zh 附加指定路径到此路径后。
* @param trackPaths Paths to append.
* @returns `this`.
*/
append(...trackPaths: TrackPath[]): TrackPath;
/**
* @zh 判断指定路径段是否是属性路径。
* @en Decides if the specific path segment is property path.
* @param index Index to the segment。
* @returns The judgement result.
*/
isPropertyAt(index: number): boolean;
/**
* @zh 将指定路径段视为属性路径，获取其描述的属性。
* @en Treats the path segment as a property path. Obtains the property it describes.
* @param index Index to the segment。
* @returns The property.
*/
parsePropertyAt(index: number): string;
/**
* @zh 判断指定路径段是否是数组元素路径。
* @en Decides if the specific path segment is an array element path.
* @param index Index to the segment。
* @returns The judgement result.
*/
isElementAt(index: number): boolean;
/**
* @zh 将指定路径段视为数组元素路径，获取其描述的数组元素。
* @en Treats the path segment as an array element path. Obtains the element index it describes.
* @param index Index to the segment。
* @returns The element index.
*/
parseElementAt(index: number): number;
/**
* @zh 判断指定路径段是否是层级路径。
* @en Decides if the specific path segment is a hierarchy path.
* @param index Index to the segment。
* @returns The judgement result.
*/
isHierarchyAt(index: number): boolean;
/**
* @zh 将指定路径段视为层级路径，获取其描述的层级路径。
* @en Treats the path segment as a hierarchy path. Obtains the hierarchy path it describes.
* @param index Index to the segment。
* @returns The hierarchy path.
*/
parseHierarchyAt(index: number): string;
/**
* @zh 判断指定路径段是否是组件路径。
* @en Decides if the specific path segment is a component path.
* @param index Index to the segment。
* @returns The judgement result.
*/
isComponentAt(index: number): boolean;
/**
* @zh 将指定路径段视为组件路径，获取其描述的组件路径。
* @en Treats the path segment as a hierarchy path. Obtains the component path it describes.
* @param index Index to the segment。
* @returns The component path.
*/
parseComponentAt(index: number): string;
/**
* @en Slices a interval of the path.
* @zh 分割指定区段上的路径。
* @param beginIndex Begin index to the segment. Default to 0.
* @param endIndex End index to the segment. Default to the last segment.
* @returns The new path.
*/
slice(beginIndex?: number, endIndex?: number): TrackPath;
/**
* @internal
*/
trace(object: unknown, beginIndex?: number, endIndex?: number): unknown;
/**
* @internal
*/
[__private._cocos_animation_tracks_track__parseTrsPathTag](): {
node: string;
property: "position" | "scale" | "rotation" | "eulerAngles";
} | null;
/**
* @internal
*/
[__private._cocos_animation_tracks_track__normalizedFollowTag](root: unknown, beginIndex: number, endIndex: number): unknown;
}
/**
* @en
* A real track animates a scalar attribute of target.
* @zh
* 实数轨道描述目标上某个标量属性的动画。
*/
export class RealTrack extends __private._cocos_animation_tracks_track__SingleChannelTrack {
/**
* @internal
*/
protected createCurve(): RealCurve;
}
/**
* @en
* A vector track animates a vector(in 2, 3, 4 dimension) attribute of target.
* @zh
* 向量轨道描述目标上某个（二、三、四维）向量属性的动画。
*/
export class VectorTrack extends Track {
constructor();
/**
* @en Gets or sets the count of components(dimension) available while evaluating of this track.
* @zh 获取或设置此轨道在求值时有效的分量数（维度）。
*/
get componentsCount(): number;
set componentsCount(value: number);
/**
* @en The four channel of the track.
* @zh 返回此轨道的四条通道。
* @returns An readonly four length array in which
* the element at n denotes the channel of n-th vector component.
*/
channels(): [
__private._cocos_animation_tracks_track__RealChannel,
__private._cocos_animation_tracks_track__RealChannel,
__private._cocos_animation_tracks_track__RealChannel,
__private._cocos_animation_tracks_track__RealChannel
];
/**
* @internal
*/
[__private._cocos_animation_define__createEvalSymbol](): __private._cocos_animation_tracks_vector_track__Vec2TrackEval | __private._cocos_animation_tracks_vector_track__Vec3TrackEval | __private._cocos_animation_tracks_vector_track__Vec4TrackEval;
}
/**
* @en
* A quaternion track animates a quaternion(rotation) attribute of target.
* @zh
* 四元数轨道描述目标上某个四元数（旋转）属性的动画。
*/
export class QuatTrack extends __private._cocos_animation_tracks_track__SingleChannelTrack {
/**
* @internal
*/
protected createCurve(): QuatCurve;
/**
* @internal
*/
[__private._cocos_animation_define__createEvalSymbol](): __private._cocos_animation_tracks_quat_track__QuatTrackEval;
}
/**
* @en
* A color track animates a color attribute of target.
* @zh
* 颜色轨道描述目标上某个颜色属性的动画。
*/
export class ColorTrack extends Track {
constructor();
/**
* @en The four channel of the track.
* @zh 返回此轨道的四条通道。
* @returns An readonly four length array in which
* the element at n denotes the channel of n-th(in order of RGBA) color component(in form of integer within 0-255).
*/
channels(): [
__private._cocos_animation_tracks_track__RealChannel,
__private._cocos_animation_tracks_track__RealChannel,
__private._cocos_animation_tracks_track__RealChannel,
__private._cocos_animation_tracks_track__RealChannel
];
/**
* @internal
*/
[__private._cocos_animation_define__createEvalSymbol](): __private._cocos_animation_tracks_color_track__ColorTrackEval;
}
/**
* @en
* A size track animates a size attribute of target.
* @zh
* 尺寸轨道描述目标上某个尺寸属性的动画。
*/
export class SizeTrack extends Track {
constructor();
/**
* @en The width channel and the height channel of the track.
* @zh 返回此轨道的宽度通道和高度通道。
* @returns An readonly array in which
* the first element is the width channel and the second element is the height channel.
*/
channels(): [
__private._cocos_animation_tracks_track__RealChannel,
__private._cocos_animation_tracks_track__RealChannel
];
/**
* @internal
*/
[__private._cocos_animation_define__createEvalSymbol](): __private._cocos_animation_tracks_size_track__SizeTrackEval;
}
/**
* @en
* An object track animates an object of attribute of target.
* @zh
* 对象轨道描述目标上某个对象类型的属性的动画。
*/
export class ObjectTrack extends __private._cocos_animation_tracks_track__SingleChannelTrack> {
/**
* @internal
*/
protected createCurve(): ObjectCurve;
}
/**
* @deprecated Since V3.3, use [[TrackPath]] instead.
*/
export function isPropertyPath(path: TargetPath): path is PropertyPath;
/**
* @deprecated Since V3.3, use [[TrackPath]] instead.
*/
export function isCustomPath(path: TargetPath, constructor: __private.__types_globals__Constructor): path is T;
/**
* @deprecated Since V3.3, use [[TrackPath]] instead.
*/
export type PropertyPath = string | number;
/**
* @deprecated Since V3.3, use [[TrackPath]] instead.
*/
export interface ICustomTargetPath {
/**
* @en
* Gets next target from current target.
* If errors are encountered, `null` should be returned.
* @zh
* 从当前目标中获取下一个目标。
* 若错误发生，应返回 `null`。
* @param target
*/
get(target: any): any;
}
/**
* @deprecated Since V3.3, use [[TrackPath]] instead.
*/
export type TargetPath = PropertyPath | ICustomTargetPath;
/**
* @deprecated Since V3.3, use [[TrackPath]] instead.
*/
export class HierarchyPath implements ICustomTargetPath {
path: string;
constructor(path?: string);
get(target: Node): Node | null;
}
/**
* @deprecated Since V3.3, use [[TrackPath]] instead.
*/
export class ComponentPath implements ICustomTargetPath {
component: string;
constructor(component?: string);
get(target: Node): Component | null;
}
/**
* @en
* Value proxies are used to set curve value to target. They are "generalized assignment".
* Every value proxy associates with a target object.
* @zh
* 曲线值代理用来设置曲线值到目标，是广义的赋值。
* 每个曲线值代理都关联着一个目标对象。
*/
export interface IValueProxy {
/**
* @en
* Gets the value from the target.
* This method is used for implementing component-wise animation in certain circumstance.
* @zh
* 从目标中获取值。某些情况下可能需要这个接口来实现分量动画。
*/
get?: () => any;
/**
* @en
* Sets a value.
* @zh
* 设置曲线值到目标对象上。
*/
set: (value: any) => void;
}
export interface IValueProxyFactory {
/**
* @en
* Returns a value proxy for specific target.
* @zh
* 返回指定目标的曲线值代理。
* @param target The target acquiring the value proxy.
* @returns The value proxy, or undefined if the proxy could not be created.
* In later case, a warn should be given before returning.
*/
forTarget(target: any): IValueProxy | undefined;
}
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export const CubicSplineVec2Value: __private._cocos_animation_cubic_spline_value__CubicSplineValueConstructor;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export type CubicSplineVec2Value = __private._cocos_animation_cubic_spline_value__ICubicSplineValue;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export const CubicSplineVec3Value: __private._cocos_animation_cubic_spline_value__CubicSplineValueConstructor;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export type CubicSplineVec3Value = __private._cocos_animation_cubic_spline_value__ICubicSplineValue;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export const CubicSplineVec4Value: __private._cocos_animation_cubic_spline_value__CubicSplineValueConstructor;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export type CubicSplineVec4Value = __private._cocos_animation_cubic_spline_value__ICubicSplineValue;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export const CubicSplineQuatValue: __private._cocos_animation_cubic_spline_value__CubicSplineValueConstructor;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export class CubicSplineNumberValue implements __private._cocos_animation_cubic_spline_value__ICubicSplineValue {
dataPoint: number;
inTangent: number;
outTangent: number;
constructor(dataPoint: number, inTangent: number, outTangent: number);
lerp(to: CubicSplineNumberValue, t: number, dt: number): number;
getNoLerp(): number;
}
/**
* @en
* An opacity type which denotes what the animation graph seems like outside the engine.
* @zh
* 一个非透明的类型，它是动画图在引擎外部的表示。
*/
export interface AnimationGraphRunTime {
/**
* @internal
*/
readonly __brand: "AnimationGraph";
}
/**
* @en
* An opacity type which denotes what the animation graph variant seems like outside the engine.
* @zh
* 一个非透明的类型，它是动画图变体在引擎外部的表示。
*/
export interface AnimationGraphVariantRunTime {
/**
* @internal
*/
readonly __brand: "AnimationGraphVariant";
}
/**
* @en
* The animation controller component applies an animation graph
* to the node which it's attached to.
* When the controller starts, the animation graph is instantiated.
* Then you may set variables or query the running statuses of the animation graph instance.
* @zh
* 将动画图应用到动画控制器组件所挂载的节点上。
* 当动画控制器开始运行时，动画图会被实例化。然后便可以设置动画图实例中的变量或者查询动画图的运行状况。
*/
export class AnimationController extends Component {
/**
* @zh
* 动画控制器所关联的动画图。
* @en
* The animation graph associated with the animation controller.
*/
get graph(): AnimationGraphRunTime | AnimationGraphVariantRunTime | null;
set graph(value: AnimationGraphRunTime | AnimationGraphVariantRunTime | null);
/**
* @zh 获取动画图的层级数量。如果控制器没有指定动画图，则返回 0。
* @en Gets the count of layers in the animation graph.
* If no animation graph is specified, 0 is returned.
*/
get layerCount(): number;
__preload(): void;
onDestroy(): void;
update(deltaTime: number): void;
/**
* @zh 获取动画图中的所有变量。
* @en Gets all the variables in the animation graph.
* @returns The iterator to the variables.
* @example
* ```ts
* for (const [name, { type }] of animationController.getVariables()) {
* log(`Name: ${name}, Type: ${type}`);
* }
* ```
*/
getVariables(): Iterable
]>;
/**
* @zh 设置动画图实例中变量的值。
* @en Sets the value of the variable in the animation graph instance.
* @param name @en Variable's name. @zh 变量的名称。
* @param value @en Variable's value. @zh 变量的值。
* @example
* ```ts
* animationController.setValue('speed', 3.14);
* animationController.setValue('crouching', true);
* animationController.setValue('attack', true);
* ```
*/
setValue(name: string, value: Value): void;
/**
* @zh 设置动画图实例中变量的值。
* @en Sets the value of the variable in the animation graph instance.
* @param name @en Variable's name. @zh 变量的名称。
* @param value @en Variable's value. @zh 变量的值。
* @example
* ```ts
* animationController.setValue('speed', 3.14);
* animationController.setValue('crouching', true);
* animationController.setValue('attack', true);
* ```
* @experimental
*/
setValue_experimental(name: string, value: Value_experimental): void;
/**
* @zh 获取动画图实例中变量的值。
* @en Gets the value of the variable in the animation graph instance.
* @param name @en Variable's name. @zh 变量的名称。
* @returns @en Variable's value. @zh 变量的值。
*/
getValue(name: string): Value | undefined;
/**
* @zh 获取动画图实例中变量的值。
* @en Gets the value of the variable in the animation graph instance.
* @param name @en Variable's name. @zh 变量的名称。
* @returns @en Variable's value. @zh 变量的值。
*/
getValue_experimental(name: string): Value_experimental | undefined;
/**
* @zh 获取动画图实例中当前状态的运行状况。
* @en Gets the running status of the current state in the animation graph instance.
* @param layer @en Index of the layer. @zh 层级索引。
* @returns @en The running status of the current state. `null` is returned if current state is not a motion state.
* @zh 当前的状态运作状态对象。如果当前的状态不是动作状态，则返回 `null`。
*/
getCurrentStateStatus(layer: number): Readonly | null;
/**
* @zh 获取动画图实例中当前状态上包含的所有动画剪辑的运行状况。
* @en Gets the running status of all the animation clips added on the current state in the animation graph instance.
* @param layer @en Index of the layer. @zh 层级索引。
* @returns @en Iterable to the animation clip statuses on current state.
* An empty iterable is returned if current state is not a motion state.
* @zh 到动画剪辑运作状态的迭代器。若当前状态不是动画状态，则返回一个空的迭代器。
*/
getCurrentClipStatuses(layer: number): Iterable>;
/**
* @zh 获取动画图实例中当前正在进行的过渡的运行状况。
* @en Gets the running status of the transition currently in progress in the animation graph instance.
* @param layer @en Index of the layer. @zh 层级索引。
* @returns @en Current transition status. `null` is returned in case of no transition.
* @zh 当前正在进行的过渡，若没有进行任何过渡，则返回 `null`。
*/
getCurrentTransition(layer: number): Readonly | null;
/**
* @zh 获取动画图实例中下一个状态的运行状况。
* @en Gets the running status of the next state in the animation graph instance.
* @param layer @en Index of the layer. @zh 层级索引。
* @returns @en The running status of the next state. `null` is returned in case of no transition or if next state is not a motion state.
* @zh 下一状态运作状态对象，若未在进行过渡或下一状态不是动画状态，则返回 `null`。
*/
getNextStateStatus(layer: number): Readonly | null;
/**
* @zh 获取动画图实例中下一个状态上添加的所有动画剪辑的运行状况。
* @en Gets the running status of all the animation clips added on the next state in the animation graph instance.
* @param layer @en Index of the layer. @zh 层级索引。
* @returns @en Iterable to the animation clip statuses on next state.
* An empty iterable is returned in case of no transition or next state is not a motion state.
* @zh 到下一状态上包含的动画剪辑运作状态的迭代器，若未在进行过渡或下一状态不是动画状态，则返回一个空的迭代器。
*/
getNextClipStatuses(layer: number): Iterable>;
/**
* @zh 获取层级权重。
* @en Gets the weight of specified layer.
* @param layer @en Index of the layer. @zh 层级索引。
*/
getLayerWeight(layer: number): number;
/**
* @zh 设置层级权重。
* @en Sets the weight of specified layer.
* @param layer @en Index of the layer. @zh 层级索引。
*/
setLayerWeight(layer: number, weight: number): void;
/**
* @zh 覆盖动画图实例中的动画剪辑。
* 对于每一对源剪辑、目标剪辑，
* 动画图（实例）中的出现的所有源剪辑都会被替换为目标剪辑，就好像动画图中一开始就使用的是目标剪辑。
* 不过，动画图当前的运转状态会依然保持不变，例如：
*
* - 若动作状态涉及的动画剪辑被替换，动作状态的播放进度百分比依然保持不变。
*
* - 若过渡的周期是相对的，即使在某一刻动画过渡的源头被替换，那么过渡的进度百分比也依然保持不变。
*
* 不管进行多少次覆盖，源剪辑应该一直指定为原始动画图中的动画剪辑。例如：
*
* ```ts
* // `originalClip` 是原始动画图中的剪辑对象，第一次希望将原剪辑覆盖为 `newClip1`，第二次希望将原剪辑覆盖为 `newClip2`
* animationController.overrideClips_experimental(new Map([ [originalClip, newClip1] ])); // 第一次覆盖
* animationController.overrideClips_experimental(new Map([ [newClip1, newClip2] ])); // 错误：第二次覆盖
* animationController.overrideClips_experimental(new Map([ [originalClip, newClip2] ])); // 正确：第二次覆盖
* ```
* @en Overrides the animation clips in animation graph instance.
* TODO
* @experimental
*/
overrideClips_experimental(overrides: ___private._cocos_animation_marionette_clip_overriding__ReadonlyClipOverrideMap): void;
/**
* @zh 获取指定辅助曲线的当前值。
* @en Gets the current value of specified auxiliary curve.
* @param curveName @en Name of the auxiliary curve. @zh 辅助曲线的名字。
* @returns @zh 指定辅助曲线的当前值，如果指定辅助曲线不存在或动画图为空则返回 0。
* @en The current value of specified auxiliary curve,
* or 0 if specified adjoint curve does not exist or if the animation graph is null.
* @experimental
*/
getAuxiliaryCurveValue_experimental(curveName: string): number;
}
/**
* @en
* Runtime clip status of a motion state.
* @zh
* 动作状态中包含的剪辑的运行状态。
*/
export interface ClipStatus {
/**
* @en
* The clip object.
* @zh
* 剪辑对象。
*/
clip: AnimationClip;
/**
* @en
* The clip's weight.
* @zh
* 剪辑的权重。
*/
weight: number;
}
/**
* @en
* Runtime status of a transition.
* @zh
* 过渡的运行状态。
*/
export interface TransitionStatus {
/**
* @en
* The duration of the transition.
* @zh
* 过渡的周期。
*/
duration: number;
/**
* @en
* The progress of the transition.
* @zh
* 过渡的进度。
*/
time: number;
}
/**
* @en
* Runtime status of a motion state.
* @zh
* 动作状态的运行状态。
*/
export interface MotionStateStatus {
/**
* For testing.
* TODO: remove it.
* @internal
*/
__DEBUG_ID__?: string;
/**
* @en
* The normalized time of the state.
* It would be the fraction part of `elapsed-time / duration` if elapsed time is non-negative,
* and would be 1 plus the fraction part of `(elapsed-time / duration)` otherwise.
* This is **NOT** the clip's progress if the state is not a clip motion or its wrap mode isn't loop.
* @zh
* 状态的规范化时间。
* 如果流逝的时间是非负的，它就是 `流逝时间 / 周期` 的小数部分；否则，它是 `(流逝时间 / 周期)` 的小数部分加 1。
* 它并不一定代表剪辑的进度，因为该状态可能并不是一个剪辑动作，或者它的循环模式并非循环。
*/
progress: number;
}
/**
* @en State machine component.
* @zh 状态机组件。
*/
export class StateMachineComponent {
/**
* @en
* Called when a motion state right after it entered.
* @zh
* 在刚刚进入动作状态时调用。
* @param controller The animation controller it within.
* @param motionStateStatus The status of the motion.
*/
onMotionStateEnter(controller: AnimationController, motionStateStatus: Readonly): void;
/**
* @en
* Called when a motion state is going to be exited.
* @zh
* 在即将退出动作状态时调用。
* @param controller The animation controller it within.
* @param motionStateStatus The status of the motion.
*/
onMotionStateExit(controller: AnimationController, motionStateStatus: Readonly): void;
/**
* @en
* Called when a motion state updated except for the first and last frame.
* @zh
* 在动作状态更新时调用，但不会在第一次和最后一次时调用。
* @param controller The animation controller it within.
* @param motionStateStatus The status of the motion.
*/
onMotionStateUpdate(controller: AnimationController, motionStateStatus: Readonly): void;
/**
* @en
* Called when a state machine right after it entered.
* @zh
* 在刚刚进入状态机时调用。
* @param controller The animation controller it within.
*/
onStateMachineEnter(controller: AnimationController): void;
/**
* @en
* Called when a state machine is going to be exited.
* @zh
* 在即将退出状态机时调用。
* @param controller The animation controller it within.
*/
onStateMachineExit(controller: AnimationController): void;
}
export type Value = number | string | boolean;
}
export interface ILerpable {
/**
* 在当前曲线值与目标曲线值之间插值。
* @param to 目标曲线值。
* @param t 插值比率。
* @param dt 当前曲线值与目标曲线值的时间间隔，单位为秒。
* @returns 插值结果。
*/
lerp(to: any, t: number, dt: number): any;
/**
* 当直接使用曲线值作为采样结果时的结果值，它应该等同于插值比率为 0 时的插值结果。
* @returns 插值比率为 0 时的插值结果。
*/
getNoLerp?(): any;
}
/**
* @zh
* 采样动画曲线。
* @en
* Samples an animation curve.
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
* @param curve @zh 动画曲线。@en The curve.
* @param sampler @zh 采样器。@en The sampler.
* @param ratio @zh 采样比率。@en Sample ratio([0, 1]).
*/
export function sampleAnimationCurve(curve: AnimCurve, sampler: RatioSampler, ratio: number): any;
/**
* @en
* Compute a new ratio by curve type.
* @zh
* 根据曲线类型计算新的比例。
* @param ratio - The origin ratio
* @param type - If it's Array, then ratio will be computed with bezierByTime.
* If it's string, then ratio will be computed with cc.easing function
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export function computeRatioByType(ratio: number, type: AnimationClip._legacy.LegacyEasingMethod): number;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export class RatioSampler {
ratios: number[];
constructor(ratios: number[]);
sample(ratio: number): number;
}
/**
* @en
* Animation curve.
* @zh
* 动画曲线。
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export class AnimCurve {
static Linear: null;
static Bezier(controlPoints: number[]): BezierControlPoints;
types?: Array<(AnimationClip._legacy.LegacyEasingMethod | null)>;
type?: AnimationClip._legacy.LegacyEasingMethod | null;
constructor(propertyCurveData: Omit, duration: number);
hasLerp(): boolean;
valueAt(index: number): any;
valueBetween(ratio: number, from: number, fromRatio: number, to: number, toRatio: number): any;
empty(): boolean;
/**
* Returns if this curve only yields constants.
*/
constant(): boolean;
}
export class EventInfo {
events: any[];
/**
* @param func event function
* @param params event params
*/
add(func: string, params: any[]): void;
}
export class AnimationManager extends System {
get blendState(): __private._cocos_3d_skeletal_animation_skeletal_animation_blending__LegacyBlendStateBuffer;
static ID: string;
addCrossFade(crossFade: __private._cocos_animation_cross_fade__CrossFade): void;
removeCrossFade(crossFade: __private._cocos_animation_cross_fade__CrossFade): void;
update(dt: number): void;
destruct(): void;
addAnimation(anim: AnimationState): void;
removeAnimation(anim: AnimationState): void;
pushDelayEvent(fn: (...args: any[]) => void, thisArg: any, args: any[]): void;
addSockets(root: Node, sockets: Socket[]): void;
removeSockets(root: Node, sockets: Socket[]): void;
}
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export function getPathFromRoot(target: Node | null, root: Node): string;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
export function getWorldTransformUntilRoot(target: Node, root: Node, outMatrix: math.Mat4): math.Mat4;
/**
* @en
* The audio clip asset.
* @zh
* 音频片段资源。
*/
export class AudioClip extends Asset {
static AudioType: typeof __private._pal_audio_type__AudioType;
protected _duration: number;
protected _loadMode: __private._pal_audio_type__AudioType;
protected _meta: __private._cocos_audio_audio_clip__AudioMeta | null;
destroy(): boolean;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
set _nativeAsset(meta: __private._cocos_audio_audio_clip__AudioMeta | null);
get _nativeAsset(): __private._cocos_audio_audio_clip__AudioMeta | null;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
get _nativeDep(): {
uuid: string;
audioLoadMode: __private._pal_audio_type__AudioType;
ext: string;
__isNative__: boolean;
};
get loadMode(): __private._pal_audio_type__AudioType;
validate(): boolean;
getDuration(): number;
/**
* @deprecated since v3.1.0, please use AudioSource.prototype.state instead.
*/
get state(): __private._pal_audio_type__AudioState;
/**
* @deprecated since v3.1.0, please use AudioSource.prototype.getCurrentTime() instead.
*/
getCurrentTime(): number;
/**
* @deprecated since v3.1.0, please use AudioSource.prototype.getVolume() instead.
*/
getVolume(): number;
/**
* @deprecated since v3.1.0, please use AudioSource.prototype.getLoop() instead.
*/
getLoop(): boolean;
/**
* @deprecated since v3.1.0, please use AudioSource.prototype.setCurrentTime() instead.
*/
setCurrentTime(time: number): void;
/**
* @deprecated since v3.1.0, please use AudioSource.prototype.setVolume() instead.
*/
setVolume(volume: number): void;
/**
* @deprecated since v3.1.0, please use AudioSource.prototype.setLoop() instead.
*/
setLoop(loop: boolean): void;
/**
* @deprecated since v3.1.0, please use AudioSource.prototype.play() instead.
*/
play(): void;
/**
* @deprecated since v3.1.0, please use AudioSource.prototype.pause() instead.
*/
pause(): void;
/**
* @deprecated since v3.1.0, please use AudioSource.prototype.stop() instead.
*/
stop(): void;
/**
* @deprecated since v3.1.0, please use AudioSource.prototype.playOneShot() instead.
*/
playOneShot(volume?: number): void;
}
/**
* @en
* A representation of a single audio source,
* contains basic functionalities like play, pause and stop.
* @zh
* 音频组件，代表单个音源，提供播放、暂停、停止等基本功能。
*/
export class AudioSource extends Component {
static get maxAudioChannel(): number;
static AudioState: typeof __private._pal_audio_type__AudioState;
static EventType: typeof __private._cocos_audio_audio_source__AudioSourceEventType;
protected _clip: AudioClip | null;
protected _player: __private._pal_audio__AudioPlayer | null;
protected _loop: boolean;
protected _playOnAwake: boolean;
protected _volume: number;
/**
* @en
* The default AudioClip to be played for this audio source.
* @zh
* 设定要播放的音频。
*/
set clip(val: AudioClip | null);
get clip(): AudioClip | null;
/**
* @en
* Is looping enabled for this audio source?
* @zh
* 是否循环播放音频？
*/
set loop(val: boolean);
get loop(): boolean;
/**
* @en
* Is the autoplay enabled?
* Note that for most platform autoplay will only start
* after a user gesture is received, according to the latest autoplay policy:
* https://www.chromium.org/audio-video/autoplay
* @zh
* 是否启用自动播放。
* 请注意，根据最新的自动播放策略，现在对大多数平台，自动播放只会在第一次收到用户输入后生效。
* 参考：https://www.chromium.org/audio-video/autoplay
*/
set playOnAwake(val: boolean);
get playOnAwake(): boolean;
/**
* @en
* The volume of this audio source (0.0 to 1.0).
* Note: Volume control may be ineffective on some platforms.
* @zh
* 音频的音量（大小范围为 0.0 到 1.0）。
* 请注意，在某些平台上，音量控制可能不起效。
*/
set volume(val: number);
get volume(): number;
onLoad(): void;
onEnable(): void;
onDisable(): void;
onDestroy(): void;
/**
* @en
* Get PCM data from specified channel.
* Currently it is only available in Native platform and Web Audio (including Web and ByteDance platforms).
*
* @zh
* 通过指定的通道获取音频的 PCM data。
* 目前仅在原生平台和 Web Audio（包括 Web 和 字节平台）中可用。
*
* @param channelIndex The channel index. 0 is left channel, 1 is right channel.
* @returns A Promise to get the PCM data after audio is loaded.
*
* @example
* ```ts
* audioSource.getPCMData(0).then(dataView => {
* if (!dataView) return;
* for (let i = 0; i < dataView.length; ++i) {
* console.log('data: ' + dataView.getData(i));
* }
* });
* ```
*/
getPCMData(channelIndex: number): Promise;
/**
* @en
* Get the sample rate of audio.
* Currently it is only available in Native platform and Web Audio (including Web and ByteDance platforms).
*
* @zh
* 获取音频的采样率。
* 目前仅在原生平台和 Web Audio（包括 Web 和 字节平台）中可用。
*
* @returns A Promise to get the sample rate after audio is loaded.
*/
getSampleRate(): Promise;
/**
* @en
* Play the clip.
* Restart if already playing.
* Resume if paused.
*
* NOTE: On Web platforms, the Auto Play Policy bans auto playing audios at the first time, because the user gesture is required.
* there are 2 ways to play audios at the first time:
* - play audios in the callback of TOUCH_END or MOUSE_UP event
* - play audios straightly, the engine will auto play audios at the next user gesture.
*
* @zh
* 开始播放。
* 如果音频处于正在播放状态，将会重新开始播放音频。
* 如果音频处于暂停状态，则会继续播放音频。
*
* 注意:在 Web 平台，Auto Play Policy 禁止首次自动播放音频，因为需要发生用户交互之后才能播放音频。
* 有两种方式实现音频首次自动播放：
* - 在 TOUCH_END 或者 MOUSE_UP 的事件回调里播放音频。
* - 直接播放音频，引擎会在下一次发生用户交互时自动播放。
*/
play(): void;
/**
* @en
* Pause the clip.
* @zh
* 暂停播放。
*/
pause(): void;
/**
* @en
* Stop the clip.
* @zh
* 停止播放。
*/
stop(): void;
/**
* @en
* Plays an AudioClip, and scales volume by volumeScale. The result volume is `audioSource.volume * volumeScale`.
* @zh
* 以指定音量倍数播放一个音频一次。最终播放的音量为 `audioSource.volume * volumeScale`。
* @param clip The audio clip to be played.
* @param volumeScale volume scaling factor wrt. current value.
*/
playOneShot(clip: AudioClip, volumeScale?: number): void;
protected _syncStates(): void;
/**
* @en
* Set current playback time, in seconds.
* @zh
* 以秒为单位设置当前播放时间。
* @param num playback time to jump to.
*/
set currentTime(num: number);
/**
* @en
* Get the current playback time, in seconds.
* @zh
* 以秒为单位获取当前播放时间。
*/
get currentTime(): number;
/**
* @en
* Get the audio duration, in seconds.
* @zh
* 获取以秒为单位的音频总时长。
*/
get duration(): number;
/**
* @en
* Get current audio state.
* @zh
* 获取当前音频状态。
*/
get state(): __private._pal_audio_type__AudioState;
/**
* @en
* Is the audio currently playing?
* @zh
* 当前音频是否正在播放？
*/
get playing(): boolean;
}
export class AudioPCMDataView {
constructor(arrayBufferView: __private._pal_audio_type__AudioBufferView, normalizeFactor: number);
constructor(arrayBuffer: ArrayBuffer, Ctor: __private.__types_globals__Constructor<__private._pal_audio_type__AudioBufferView>, normalizeFactor: number);
get length(): number;
getData(offset: number): number;
}
/**
* @en The root manager of the renderer which manages all device resources and the render pipeline.
* @zh 基础渲染器管理类，管理所有设备相关的资源创建以及渲染管线。
*/
export class Root {
/**
* @en The GFX device
* @zh GFX 设备
*/
get device(): gfx.Device;
/**
* @en The main window
* @zh 主窗口
*/
get mainWindow(): __private._cocos_render_scene_core_render_window__RenderWindow | null;
/**
* @en The current active window
* @zh 当前激活的窗口
*/
set curWindow(window: __private._cocos_render_scene_core_render_window__RenderWindow | null);
get curWindow(): __private._cocos_render_scene_core_render_window__RenderWindow | null;
/**
* @e The temporary window for data transmission
* @zh 临时窗口（用于数据传输）
* @internal
*/
set tempWindow(window: __private._cocos_render_scene_core_render_window__RenderWindow | null);
get tempWindow(): __private._cocos_render_scene_core_render_window__RenderWindow | null;
/**
* @en The windows list
* @zh 窗口列表
*/
get windows(): __private._cocos_render_scene_core_render_window__RenderWindow[];
/**
* @zh
* 启用自定义渲染管线
*/
get usesCustomPipeline(): boolean;
/**
* @en The render pipeline
* @zh 渲染管线
*/
get pipeline(): __private._cocos_rendering_custom_pipeline__PipelineRuntime;
/**
* @en The custom render pipeline
* @zh 自定义渲染管线
*/
get customPipeline(): rendering.BasicPipeline;
/**
* @en The pipeline events
* @zh 渲染管线事件
*/
get pipelineEvent(): __private._cocos_rendering_pipeline_event__IPipelineEvent;
/**
* @en The draw batch manager for 2D UI, for engine internal usage, user do not need to use this.
* @zh 2D UI 渲染合批管理器，引擎内部使用，用户无需使用此接口
*/
get batcher2D(): UI;
/**
* @en Render scenes list
* @zh 渲染场景列表
*/
get scenes(): renderer.RenderScene[];
/**
* @en The debug view manager for rendering
* @zh 渲染调试管理器
*/
get debugView(): DebugView;
/**
* @en The time cumulated in seconds since the game began running.
* @zh 累计时间（秒）。
*/
get cumulativeTime(): number;
/**
* @en The current frame time in seconds.
* @zh 帧时间（秒）。
*/
get frameTime(): number;
/**
* @en The frame count during the last second
* @zh 一秒内的累计帧数
*/
get frameCount(): number;
/**
* @en The recent frame rate for the last second
* @zh 当前每秒帧率
*/
get fps(): number;
/**
* @en The wanted frame rate set by user
* @zh 每秒设定帧率
*/
set fixedFPS(fps: number);
get fixedFPS(): number;
/**
* @internal
*/
get dataPoolManager(): __private._cocos_3d_skeletal_animation_data_pool_manager__DataPoolManager;
/**
* @en Whether the built-in deferred pipeline is used.
* @zh 是否启用内置延迟渲染管线
*/
get useDeferredPipeline(): boolean;
get cameraList(): renderer.scene.Camera[];
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
_createSceneFun: (root: Root) => renderer.RenderScene;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
_createWindowFun: (root: Root) => __private._cocos_render_scene_core_render_window__RenderWindow;
/**
* @en The constructor of the root, user shouldn't create the root instance, it's managed by the [[Director]].
* @zh 构造函数，用户不应该自己创建任何 Root 对象，它是由 [[Director]] 管理的。
* @param device GFX device
*/
constructor(device: gfx.Device);
/**
* @en The initialization function, user shouldn't initialize the root, it's managed by the [[Director]].
* @zh 初始化函数，用户不应该自己初始化 Root，它是由 [[Director]] 管理的。
* @param info Root initialization information
*/
initialize(info: __private._cocos_root__IRootInfo): void;
/**
* @en Destroy the root, user shouldn't invoke this function, it will cause undefined behavior.
* @zh 销毁 Root，用户不应该调用此方法，会造成未知行为。
*/
destroy(): void;
/**
* @en Resize the on-screen render windows.
* @zh 重置在屏窗口的大小。
* @param width The new width of the window.
* @param height The new height of the window.
* @param windowId The system window ID, optional for now.
*/
resize(width: number, height: number, windowId?: number): void;
/**
* @en Setup the render pipeline
* @zh 设置渲染管线
* @param rppl The render pipeline
* @returns The setup is successful or not
*/
setRenderPipeline(rppl?: RenderPipeline): boolean;
/**
* @en Notify the pipeline and all scenes that the global pipeline state have been updated so that they can update their render data and states.
* @zh 通知渲染管线和所有场景全局管线状态已更新，需要更新自身状态。
*/
onGlobalPipelineStateChanged(): void;
/**
* @en Active the render window as the [[curWindow]]
* @zh 激活指定窗口为当前窗口 [[curWindow]]
* @param window The render window to be activated
*/
activeWindow(window: __private._cocos_render_scene_core_render_window__RenderWindow): void;
/**
* @en Reset the time cumulated
* @zh 重置累计时间
*/
resetCumulativeTime(): void;
/**
* @en The entry function of the render process for every frame.
* @zh 用于每帧执行渲染流程的入口函数
* @param deltaTime @en The delta time since last update. @zh 距离上一帧间隔时间
*/
frameMove(deltaTime: number): void;
/**
* @en Create a render window
* @zh 创建一个新的窗口
* @param info @en The window creation information @zh 窗口描述信息
*/
createWindow(info: __private._cocos_render_scene_core_render_window__IRenderWindowInfo): __private._cocos_render_scene_core_render_window__RenderWindow | null;
/**
* @en Destroy a render window
* @zh 销毁指定的窗口
* @param window The render window to be destroyed
*/
destroyWindow(window: __private._cocos_render_scene_core_render_window__RenderWindow): void;
/**
* @en Destroy all render windows
* @zh 销毁全部窗口
*/
destroyWindows(): void;
/**
* @en Create a render scene
* @zh 创建渲染场景
* @param info @en The creation information for render scene @zh 渲染场景描述信息
*/
createScene(info: renderer.IRenderSceneInfo): renderer.RenderScene;
/**
* @en Destroy the given render scene
* @zh 销毁指定的渲染场景
* @param scene @en The render scene to be destroyed. @zh 要销毁的渲染场景
*/
destroyScene(scene: renderer.RenderScene): void;
/**
* @en Destroy all render scenes.
* @zh 销毁全部场景。
*/
destroyScenes(): void;
/**
* @en Create a model
* @zh 创建模型
* @param ModelCtor @en The class of the model @zh 模型的类
* @returns The model created
*/
createModel(ModelCtor: typeof renderer.scene.Model): T;
/**
* @en Destroy the given model
* @zh 销毁指定的模型
* @param m @en The model to be destroyed @zh 要销毁的模型
*/
destroyModel(m: renderer.scene.Model): void;
/**
* @en Create a camera
* @zh 创建一个相机
* @returns The camera created.
*/
createCamera(): renderer.scene.Camera;
/**
* @en Create a light source
* @zh 创建光源
* @param LightCtor @en The class of the light @zh 光源的类
* @returns The light created
*/
createLight(LightCtor: new () => T): T;
/**
* @en Destroy the given light
* @zh 销毁指定的光源
* @param l @en The light to be destroyed @zh 要销毁的光源
*/
destroyLight(l: renderer.scene.Light): void;
/**
* @en recycle the given light to light object pool
* @zh 回收指定的光源到对象池
* @param l @en The light to be recycled @zh 要回收的光源
*/
recycleLight(l: renderer.scene.Light): void;
}
export namespace gfx {
/**
* @en GFX sampler.
* @zh GFX 采样器。
*/
export class Sampler extends GFXObject {
get info(): Readonly;
get hash(): number;
protected _info: SamplerInfo;
protected _hash: number;
constructor(info: Readonly, hash: number);
static computeHash(info: Readonly): Filter;
static unpackFromHash(hash: number): SamplerInfo;
}
export class SamplerInfo {
minFilter: Filter;
magFilter: Filter;
mipFilter: Filter;
addressU: Address;
addressV: Address;
addressW: Address;
maxAnisotropy: number;
cmpFunc: ComparisonFunc;
constructor(minFilter?: Filter, magFilter?: Filter, mipFilter?: Filter, addressU?: Address, addressV?: Address, addressW?: Address, maxAnisotropy?: number, cmpFunc?: ComparisonFunc);
copy(info: Readonly): SamplerInfo;
}
/**
* @en Get the memory size of the specified type.
* @zh 得到 GFX 数据类型的大小。
* @param type The target type.
*/
export function GetTypeSize(type: Type): number;
/**
* @en GFX descriptor sets.
* @zh GFX 描述符集组。
*/
export abstract class DescriptorSet extends GFXObject {
get layout(): DescriptorSetLayout;
protected _layout: DescriptorSetLayout | null;
protected _buffers: Buffer[];
protected _textures: Texture[];
protected _samplers: Sampler[];
protected _isDirty: boolean;
constructor();
abstract initialize(info: Readonly): void;
abstract destroy(): void;
abstract update(): void;
/**
* @en Bind buffer to the specified descriptor.
* @zh 在指定的描述符位置上绑定缓冲。
* @param binding The target binding.
* @param buffer The buffer to be bound.
*/
bindBuffer(binding: number, buffer: Buffer, index?: number): void;
/**
* @en Bind sampler to the specified descriptor.
* @zh 在指定的描述符位置上绑定采样器。
* @param binding The target binding.
* @param sampler The sampler to be bound.
*/
bindSampler(binding: number, sampler: Sampler, index?: number): void;
/**
* @en Bind texture to the specified descriptor.
* @zh 在指定的描述符位置上绑定纹理。
* @param binding The target binding.
* @param texture The texture to be bound.
*/
bindTexture(binding: number, texture: Texture, index?: number, flags?: AccessFlags): void;
/**
* @en Get buffer from the specified binding location.
* @zh 获取当前指定绑定位置上的缓冲。
* @param binding The target binding.
*/
getBuffer(binding: number, index?: number): Buffer;
/**
* @en Get sampler from the specified binding location.
* @zh 获取当前指定绑定位置上的采样器。
* @param binding The target binding.
*/
getSampler(binding: number, index?: number): Sampler;
/**
* @en Get texture from the specified binding location.
* @zh 获取当前指定绑定位置上的贴图。
* @param binding The target binding.
*/
getTexture(binding: number, index?: number): Texture;
}
/**
* @en GFX buffer.
* @zh GFX 缓冲。
*/
export abstract class Buffer extends GFXObject {
/**
* @en Usage type of the buffer.
* @zh 缓冲使用方式。
*/
get usage(): BufferUsage;
/**
* @en Memory usage of the buffer.
* @zh 缓冲的内存使用方式。
*/
get memUsage(): MemoryUsage;
/**
* @en Size of the buffer.
* @zh 缓冲大小。
*/
get size(): number;
/**
* @en Stride of the buffer.
* @zh 缓冲步长。
*/
get stride(): number;
/**
* @en Count of the buffer wrt. stride.
* @zh 缓冲条目数量。
*/
get count(): number;
get flags(): BufferFlags;
protected _usage: BufferUsage;
protected _memUsage: MemoryUsage;
protected _size: number;
protected _stride: number;
protected _count: number;
protected _flags: BufferFlags;
protected _isBufferView: boolean;
constructor();
abstract initialize(info: Readonly | Readonly): void;
abstract destroy(): void;
/**
* @en Resize the buffer.
* @zh 重置缓冲大小。
* @param size The new buffer size.
*/
abstract resize(size: number): void;
/**
* @en Update the buffer data.
* @zh 更新缓冲内容。
* @param buffer The new buffer data.
* @param size Size in bytes to be updated.
*/
abstract update(buffer: Readonly, size?: number): void;
}
/**
* @en GFX command buffer.
* @zh GFX 命令缓冲。
*/
export abstract class CommandBuffer extends GFXObject {
/**
* @en Type of the command buffer.
* @zh 命令缓冲类型。
*/
get type(): CommandBufferType;
/**
* @en Type of the command buffer.
* @zh 命令缓冲类型。
*/
get queue(): Queue;
/**
* @en Number of draw calls currently recorded.
* @zh 绘制调用次数。
*/
get numDrawCalls(): number;
/**
* @en Number of instances currently recorded.
* @zh 绘制 Instance 数量。
*/
get numInstances(): number;
/**
* @en Number of triangles currently recorded.
* @zh 绘制三角形数量。
*/
get numTris(): number;
protected _queue: Queue | null;
protected _type: CommandBufferType;
protected _numDrawCalls: number;
protected _numInstances: number;
protected _numTris: number;
constructor();
abstract initialize(info: Readonly): void;
abstract destroy(): void;
/**
* @en Begin recording commands.
* @zh 开始记录命令。
* @param renderPass [Secondary Command Buffer Only] The render pass the subsequent commands will be executed in
* @param subpass [Secondary Command Buffer Only] The subpass the subsequent commands will be executed in
* @param frameBuffer [Secondary Command Buffer Only, Optional] The framebuffer to be used in the subpass
*/
abstract begin(renderPass?: RenderPass, subpass?: number, frameBuffer?: Framebuffer): void;
/**
* @en End recording commands.
* @zh 结束记录命令。
*/
abstract end(): void;
/**
* @en Begin render pass.
* @zh 开始 RenderPass。
* @param framebuffer The frame buffer used.
* @param renderArea The target render area.
* @param clearFlag The clear flags.
* @param clearColors The clearing colors.
* @param clearDepth The clearing depth.
* @param clearStencil The clearing stencil.
*/
abstract beginRenderPass(renderPass: RenderPass, framebuffer: Framebuffer, renderArea: Readonly, clearColors: Readonly, clearDepth: number, clearStencil: number): void;
/**
* @en End render pass.
* @zh 结束 RenderPass。
*/
abstract endRenderPass(): void;
/**
* @en Bind pipeline state.
* @zh 绑定 GFX 管线状态。
* @param pipelineState The pipeline state to be bound.
*/
abstract bindPipelineState(pipelineState: PipelineState): void;
/**
* @en Bind a descriptor set. Note that the corresponding PiplieneState has to be bound first
* before calling this function, or the dynamic offset specified may be invalidated.
* @zh 绑定 GFX 描述符集。注意在调用此函数前，必须先绑定对应的 PipelineState，否则 dynamic offset 可能无效。
* @param set The target descriptor set index.
* @param descriptorSet The descriptor set to be bound.
* @param dynamicOffsets The offset numbers for dynamic bindings.
*/
abstract bindDescriptorSet(set: number, descriptorSet: DescriptorSet, dynamicOffsets?: Readonly): void;
/**
* @en Bind input assembler.
* @zh 绑定 GFX 输入汇集器。
* @param inputAssembler The input assembler to be bound.
*/
abstract bindInputAssembler(inputAssembler: InputAssembler): void;
/**
* @en Set viewport.
* @zh 设置视口。
* @param viewport The new viewport.
*/
abstract setViewport(viewport: Readonly): void;
/**
* @en Set scissor range.
* @zh 设置剪裁区域。
* @param scissor The new scissor range.
*/
abstract setScissor(scissor: Readonly): void;
/**
* @en Set line width.
* @zh 设置线宽。
* @param lineWidth The new line width.
*/
abstract setLineWidth(lineWidth: number): void;
/**
* @en Set depth bias.
* @zh 设置深度偏移。
* @param depthBiasConstantFactor The new depth bias factor.
* @param depthBiasClamp The new depth bias clamp threshold.
* @param depthBiasSlopeFactor The new depth bias slope factor.
*/
abstract setDepthBias(depthBiasConstantFactor: number, depthBiasClamp: number, depthBiasSlopeFactor: number): void;
/**
* @en Set blend constants.
* @zh 设置混合因子。
* @param blendConstants The new blend constants.
*/
abstract setBlendConstants(blendConstants: Readonly): void;
/**
* @en Set depth bound.
* @zh 设置深度边界。
* @param minDepthBounds The new minimum depth bound.
* @param maxDepthBounds The new maximum depth bound.
*/
abstract setDepthBound(minDepthBounds: number, maxDepthBounds: number): void;
/**
* @en Set stencil write mask.
* @zh 设置模板写掩码。
* @param face The effective triangle face.
* @param writeMask The new stencil write mask.
*/
abstract setStencilWriteMask(face: StencilFace, writeMask: number): void;
/**
* @en Set stencil compare mask.
* @zh 设置模板比较掩码。
* @param face The effective triangle face.
* @param reference The new stencil reference constant.
* @param compareMask The new stencil read mask.
*/
abstract setStencilCompareMask(face: StencilFace, reference: number, compareMask: number): void;
/**
* @en Draw the specified primitives.
* @zh 绘制。
* @param infoOrAssembler The draw call information.
*/
abstract draw(infoOrAssembler: Readonly | Readonly): void;
/**
* @en Update buffer.
* @zh 更新缓冲。
* @param buffer The buffer to be updated.
* @param data The source data.
* @param size Size in bytes to be updated.
*/
abstract updateBuffer(buffer: Buffer, data: Readonly, size?: number): void;
/**
* @en Copy buffer to texture.
* @zh 拷贝缓冲到纹理。
* @param srcBuff The buffer to be copied.
* @param dstTex The texture to copy to.
* @param dstLayout The target texture layout.
* @param regions The region descriptions.
*/
abstract copyBuffersToTexture(buffers: Readonly, texture: Texture, regions: Readonly): void;
/**
* @en Execute specified command buffers.
* @zh 执行一组命令缓冲。
* @param cmdBuffs The command buffers to be executed.
* @param count The number of command buffers to be executed.
*/
abstract execute(cmdBuffs: Readonly, count: number): void;
/**
* @en Insert pipeline memory barriers.
* @zh 插入管线内存屏障。
* @param barrier The global memory barrier to apply.
* @param textureBarriers The texture memory barriers to apply.
*/
abstract pipelineBarrier(barrier: Readonly | null, bufferBarriers?: Readonly<__private._cocos_gfx_base_states_buffer_barrier__BufferBarrier[]>, buffers?: Readonly, textureBarriers?: Readonly, textures?: Readonly): void;
/**
* @en blit data from regions of source texture to regions of destination texture.
* @zh 将数据从源纹理的区域拷贝到目标纹理的区域。
*
* @param srcTexture The source texture.
* @param dstTexture The destination texture.
* @param regions The region descriptions.
* @param filter The filter to use.
*/
abstract blitTexture(srcTexture: Readonly, dstTexture: Texture, regions: Readonly, filter: Filter): void;
}
export function IsPowerOf2(x: number): boolean;
/**
* @en Get memory size of the specified fomat.
* @zh 获取指定格式对应的内存大小。
* @param format The target format.
* @param width The target width.
* @param height The target height.
* @param depth The target depth.
*/
export function FormatSize(format: Format, width: number, height: number, depth: number): number;
/**
* @en Get memory size of the specified surface.
* @zh GFX 格式表面内存大小。
* @param format The target format.
* @param width The target width.
* @param height The target height.
* @param depth The target depth.
* @param mips The target mip levels.
*/
export function FormatSurfaceSize(format: Format, width: number, height: number, depth: number, mips: number): number;
export function getTypedArrayConstructor(info: FormatInfo): __private.__types_globals__TypedArrayConstructor;
export function formatAlignment(format: Format): FormatAlignment;
export function alignTo(size: number, alignment: number): number;
/**
* ========================= !DO NOT CHANGE THE FOLLOWING SECTION MANUALLY! =========================
* The following section is auto-generated from native/cocos/renderer/core/gfx/GFXDef-common.h
* by the script native/tools/gfx-define-generator/generate.js.
* Changes to these public interfaces should be made there first and synced back.
* ========================= !DO NOT CHANGE THE FOLLOWING SECTION MANUALLY! =========================
*/
/**
* @en Graphics object type
* @zh 图形API对象的类型
*/
export enum ObjectType {
UNKNOWN = 0,
SWAPCHAIN = 1,
BUFFER = 2,
TEXTURE = 3,
RENDER_PASS = 4,
FRAMEBUFFER = 5,
SAMPLER = 6,
SHADER = 7,
DESCRIPTOR_SET_LAYOUT = 8,
PIPELINE_LAYOUT = 9,
PIPELINE_STATE = 10,
DESCRIPTOR_SET = 11,
INPUT_ASSEMBLER = 12,
COMMAND_BUFFER = 13,
QUEUE = 14,
QUERY_POOL = 15,
GLOBAL_BARRIER = 16,
TEXTURE_BARRIER = 17,
BUFFER_BARRIER = 18,
COUNT = 19
}
export enum Status {
UNREADY = 0,
FAILED = 1,
SUCCESS = 2
}
export enum API {
UNKNOWN = 0,
GLES2 = 1,
GLES3 = 2,
METAL = 3,
VULKAN = 4,
NVN = 5,
WEBGL = 6,
WEBGL2 = 7,
WEBGPU = 8
}
export enum SurfaceTransform {
IDENTITY = 0,
ROTATE_90 = 1,
ROTATE_180 = 2,
ROTATE_270 = 3
}
export enum Feature {
ELEMENT_INDEX_UINT = 0,
INSTANCED_ARRAYS = 1,
MULTIPLE_RENDER_TARGETS = 2,
BLEND_MINMAX = 3,
COMPUTE_SHADER = 4,
INPUT_ATTACHMENT_BENEFIT = 5,
SUBPASS_COLOR_INPUT = 6,
SUBPASS_DEPTH_STENCIL_INPUT = 7,
RASTERIZATION_ORDER_COHERENT = 8,
MULTI_SAMPLE_RESOLVE_DEPTH_STENCIL = 9,
COUNT = 10
}
export enum Format {
UNKNOWN = 0,
A8 = 1,
L8 = 2,
LA8 = 3,
R8 = 4,
R8SN = 5,
R8UI = 6,
R8I = 7,
R16F = 8,
R16UI = 9,
R16I = 10,
R32F = 11,
R32UI = 12,
R32I = 13,
RG8 = 14,
RG8SN = 15,
RG8UI = 16,
RG8I = 17,
RG16F = 18,
RG16UI = 19,
RG16I = 20,
RG32F = 21,
RG32UI = 22,
RG32I = 23,
RGB8 = 24,
SRGB8 = 25,
RGB8SN = 26,
RGB8UI = 27,
RGB8I = 28,
RGB16F = 29,
RGB16UI = 30,
RGB16I = 31,
RGB32F = 32,
RGB32UI = 33,
RGB32I = 34,
RGBA8 = 35,
BGRA8 = 36,
SRGB8_A8 = 37,
RGBA8SN = 38,
RGBA8UI = 39,
RGBA8I = 40,
RGBA16F = 41,
RGBA16UI = 42,
RGBA16I = 43,
RGBA32F = 44,
RGBA32UI = 45,
RGBA32I = 46,
R5G6B5 = 47,
R11G11B10F = 48,
RGB5A1 = 49,
RGBA4 = 50,
RGB10A2 = 51,
RGB10A2UI = 52,
RGB9E5 = 53,
DEPTH = 54,
DEPTH_STENCIL = 55,
BC1 = 56,
BC1_ALPHA = 57,
BC1_SRGB = 58,
BC1_SRGB_ALPHA = 59,
BC2 = 60,
BC2_SRGB = 61,
BC3 = 62,
BC3_SRGB = 63,
BC4 = 64,
BC4_SNORM = 65,
BC5 = 66,
BC5_SNORM = 67,
BC6H_UF16 = 68,
BC6H_SF16 = 69,
BC7 = 70,
BC7_SRGB = 71,
ETC_RGB8 = 72,
ETC2_RGB8 = 73,
ETC2_SRGB8 = 74,
ETC2_RGB8_A1 = 75,
ETC2_SRGB8_A1 = 76,
ETC2_RGBA8 = 77,
ETC2_SRGB8_A8 = 78,
EAC_R11 = 79,
EAC_R11SN = 80,
EAC_RG11 = 81,
EAC_RG11SN = 82,
PVRTC_RGB2 = 83,
PVRTC_RGBA2 = 84,
PVRTC_RGB4 = 85,
PVRTC_RGBA4 = 86,
PVRTC2_2BPP = 87,
PVRTC2_4BPP = 88,
ASTC_RGBA_4X4 = 89,
ASTC_RGBA_5X4 = 90,
ASTC_RGBA_5X5 = 91,
ASTC_RGBA_6X5 = 92,
ASTC_RGBA_6X6 = 93,
ASTC_RGBA_8X5 = 94,
ASTC_RGBA_8X6 = 95,
ASTC_RGBA_8X8 = 96,
ASTC_RGBA_10X5 = 97,
ASTC_RGBA_10X6 = 98,
ASTC_RGBA_10X8 = 99,
ASTC_RGBA_10X10 = 100,
ASTC_RGBA_12X10 = 101,
ASTC_RGBA_12X12 = 102,
ASTC_SRGBA_4X4 = 103,
ASTC_SRGBA_5X4 = 104,
ASTC_SRGBA_5X5 = 105,
ASTC_SRGBA_6X5 = 106,
ASTC_SRGBA_6X6 = 107,
ASTC_SRGBA_8X5 = 108,
ASTC_SRGBA_8X6 = 109,
ASTC_SRGBA_8X8 = 110,
ASTC_SRGBA_10X5 = 111,
ASTC_SRGBA_10X6 = 112,
ASTC_SRGBA_10X8 = 113,
ASTC_SRGBA_10X10 = 114,
ASTC_SRGBA_12X10 = 115,
ASTC_SRGBA_12X12 = 116,
COUNT = 117
}
export enum FormatType {
NONE = 0,
UNORM = 1,
SNORM = 2,
UINT = 3,
INT = 4,
UFLOAT = 5,
FLOAT = 6
}
export enum Type {
UNKNOWN = 0,
BOOL = 1,
BOOL2 = 2,
BOOL3 = 3,
BOOL4 = 4,
INT = 5,
INT2 = 6,
INT3 = 7,
INT4 = 8,
UINT = 9,
UINT2 = 10,
UINT3 = 11,
UINT4 = 12,
FLOAT = 13,
FLOAT2 = 14,
FLOAT3 = 15,
FLOAT4 = 16,
MAT2 = 17,
MAT2X3 = 18,
MAT2X4 = 19,
MAT3X2 = 20,
MAT3 = 21,
MAT3X4 = 22,
MAT4X2 = 23,
MAT4X3 = 24,
MAT4 = 25,
SAMPLER1D = 26,
SAMPLER1D_ARRAY = 27,
SAMPLER2D = 28,
SAMPLER2D_ARRAY = 29,
SAMPLER3D = 30,
SAMPLER_CUBE = 31,
SAMPLER = 32,
TEXTURE1D = 33,
TEXTURE1D_ARRAY = 34,
TEXTURE2D = 35,
TEXTURE2D_ARRAY = 36,
TEXTURE3D = 37,
TEXTURE_CUBE = 38,
IMAGE1D = 39,
IMAGE1D_ARRAY = 40,
IMAGE2D = 41,
IMAGE2D_ARRAY = 42,
IMAGE3D = 43,
IMAGE_CUBE = 44,
SUBPASS_INPUT = 45,
COUNT = 46
}
export enum BufferUsageBit {
NONE = 0,
TRANSFER_SRC = 1,
TRANSFER_DST = 2,
INDEX = 4,
VERTEX = 8,
UNIFORM = 16,
STORAGE = 32,
INDIRECT = 64
}
export enum BufferFlagBit {
NONE = 0
}
export enum MemoryAccessBit {
NONE = 0,
READ_ONLY = 1,
WRITE_ONLY = 2,
READ_WRITE = 3
}
export enum MemoryUsageBit {
NONE = 0,
DEVICE = 1,
HOST = 2
}
export enum TextureType {
TEX1D = 0,
TEX2D = 1,
TEX3D = 2,
CUBE = 3,
TEX1D_ARRAY = 4,
TEX2D_ARRAY = 5
}
export enum TextureUsageBit {
NONE = 0,
TRANSFER_SRC = 1,
TRANSFER_DST = 2,
SAMPLED = 4,
STORAGE = 8,
COLOR_ATTACHMENT = 16,
DEPTH_STENCIL_ATTACHMENT = 32,
INPUT_ATTACHMENT = 64
}
export enum TextureFlagBit {
NONE = 0,
GEN_MIPMAP = 1,
GENERAL_LAYOUT = 2,
EXTERNAL_OES = 4,
EXTERNAL_NORMAL = 8,
LAZILY_ALLOCATED = 16,
MUTABLE_VIEW_FORMAT = 64,
MUTABLE_STORAGE = 128
}
export enum FormatFeatureBit {
NONE = 0,
RENDER_TARGET = 1,
SAMPLED_TEXTURE = 2,
LINEAR_FILTER = 4,
STORAGE_TEXTURE = 8,
VERTEX_ATTRIBUTE = 16
}
export enum SampleCount {
X1 = 1,
X2 = 2,
X4 = 4,
X8 = 8,
X16 = 16,
X32 = 32,
X64 = 64
}
export enum VsyncMode {
OFF = 0,
ON = 1,
RELAXED = 2,
MAILBOX = 3,
HALF = 4
}
export enum Filter {
NONE = 0,
POINT = 1,
LINEAR = 2,
ANISOTROPIC = 3
}
export enum Address {
WRAP = 0,
MIRROR = 1,
CLAMP = 2,
BORDER = 3
}
export enum ComparisonFunc {
NEVER = 0,
LESS = 1,
EQUAL = 2,
LESS_EQUAL = 3,
GREATER = 4,
NOT_EQUAL = 5,
GREATER_EQUAL = 6,
ALWAYS = 7
}
export enum StencilOp {
ZERO = 0,
KEEP = 1,
REPLACE = 2,
INCR = 3,
DECR = 4,
INVERT = 5,
INCR_WRAP = 6,
DECR_WRAP = 7
}
export enum BlendFactor {
ZERO = 0,
ONE = 1,
SRC_ALPHA = 2,
DST_ALPHA = 3,
ONE_MINUS_SRC_ALPHA = 4,
ONE_MINUS_DST_ALPHA = 5,
SRC_COLOR = 6,
DST_COLOR = 7,
ONE_MINUS_SRC_COLOR = 8,
ONE_MINUS_DST_COLOR = 9,
SRC_ALPHA_SATURATE = 10,
CONSTANT_COLOR = 11,
ONE_MINUS_CONSTANT_COLOR = 12,
CONSTANT_ALPHA = 13,
ONE_MINUS_CONSTANT_ALPHA = 14
}
export enum BlendOp {
ADD = 0,
SUB = 1,
REV_SUB = 2,
MIN = 3,
MAX = 4
}
export enum ColorMask {
NONE = 0,
R = 1,
G = 2,
B = 4,
A = 8,
ALL = 15
}
export enum ShaderStageFlagBit {
NONE = 0,
VERTEX = 1,
CONTROL = 2,
EVALUATION = 4,
GEOMETRY = 8,
FRAGMENT = 16,
COMPUTE = 32,
ALL = 63
}
export enum LoadOp {
LOAD = 0,
CLEAR = 1,
DISCARD = 2
}
export enum StoreOp {
STORE = 0,
DISCARD = 1
}
export enum AccessFlagBit {
NONE = 0,
INDIRECT_BUFFER = 1,
INDEX_BUFFER = 2,
VERTEX_BUFFER = 4,
VERTEX_SHADER_READ_UNIFORM_BUFFER = 8,
VERTEX_SHADER_READ_TEXTURE = 16,
VERTEX_SHADER_READ_OTHER = 32,
FRAGMENT_SHADER_READ_UNIFORM_BUFFER = 64,
FRAGMENT_SHADER_READ_TEXTURE = 128,
FRAGMENT_SHADER_READ_COLOR_INPUT_ATTACHMENT = 256,
FRAGMENT_SHADER_READ_DEPTH_STENCIL_INPUT_ATTACHMENT = 512,
FRAGMENT_SHADER_READ_OTHER = 1024,
COLOR_ATTACHMENT_READ = 2048,
DEPTH_STENCIL_ATTACHMENT_READ = 4096,
COMPUTE_SHADER_READ_UNIFORM_BUFFER = 8192,
COMPUTE_SHADER_READ_TEXTURE = 16384,
COMPUTE_SHADER_READ_OTHER = 32768,
TRANSFER_READ = 65536,
HOST_READ = 131072,
PRESENT = 262144,
VERTEX_SHADER_WRITE = 524288,
FRAGMENT_SHADER_WRITE = 1048576,
COLOR_ATTACHMENT_WRITE = 2097152,
DEPTH_STENCIL_ATTACHMENT_WRITE = 4194304,
COMPUTE_SHADER_WRITE = 8388608,
TRANSFER_WRITE = 16777216,
HOST_PREINITIALIZED = 33554432,
HOST_WRITE = 67108864
}
export enum ResolveMode {
NONE = 0,
SAMPLE_ZERO = 1,
AVERAGE = 2,
MIN = 3,
MAX = 4
}
export enum PipelineBindPoint {
GRAPHICS = 0,
COMPUTE = 1,
RAY_TRACING = 2
}
export enum PrimitiveMode {
POINT_LIST = 0,
LINE_LIST = 1,
LINE_STRIP = 2,
LINE_LOOP = 3,
LINE_LIST_ADJACENCY = 4,
LINE_STRIP_ADJACENCY = 5,
ISO_LINE_LIST = 6,
TRIANGLE_LIST = 7,
TRIANGLE_STRIP = 8,
TRIANGLE_FAN = 9,
TRIANGLE_LIST_ADJACENCY = 10,
TRIANGLE_STRIP_ADJACENCY = 11,
TRIANGLE_PATCH_ADJACENCY = 12,
QUAD_PATCH_LIST = 13
}
export enum PolygonMode {
FILL = 0,
POINT = 1,
LINE = 2
}
export enum ShadeModel {
GOURAND = 0,
FLAT = 1
}
export enum CullMode {
NONE = 0,
FRONT = 1,
BACK = 2
}
export enum DynamicStateFlagBit {
NONE = 0,
LINE_WIDTH = 1,
DEPTH_BIAS = 2,
BLEND_CONSTANTS = 4,
DEPTH_BOUNDS = 8,
STENCIL_WRITE_MASK = 16,
STENCIL_COMPARE_MASK = 32
}
export enum StencilFace {
FRONT = 1,
BACK = 2,
ALL = 3
}
export enum DescriptorType {
UNKNOWN = 0,
UNIFORM_BUFFER = 1,
DYNAMIC_UNIFORM_BUFFER = 2,
STORAGE_BUFFER = 4,
DYNAMIC_STORAGE_BUFFER = 8,
SAMPLER_TEXTURE = 16,
SAMPLER = 32,
TEXTURE = 64,
STORAGE_IMAGE = 128,
INPUT_ATTACHMENT = 256
}
export enum QueueType {
GRAPHICS = 0,
COMPUTE = 1,
TRANSFER = 2
}
export enum QueryType {
OCCLUSION = 0,
PIPELINE_STATISTICS = 1,
TIMESTAMP = 2
}
export enum CommandBufferType {
PRIMARY = 0,
SECONDARY = 1
}
export enum ClearFlagBit {
NONE = 0,
COLOR = 1,
DEPTH = 2,
STENCIL = 4,
DEPTH_STENCIL = 6,
ALL = 7
}
export enum BarrierType {
FULL = 0,
SPLIT_BEGIN = 1,
SPLIT_END = 2
}
export enum PassType {
RASTER = 0,
COMPUTE = 1,
COPY = 2,
MOVE = 3,
RAYTRACE = 4,
PRESENT = 5
}
export type BufferUsage = BufferUsageBit;
export type BufferFlags = BufferFlagBit;
export type MemoryAccess = MemoryAccessBit;
export type MemoryUsage = MemoryUsageBit;
export type TextureUsage = TextureUsageBit;
export type TextureFlags = TextureFlagBit;
export type FormatFeature = FormatFeatureBit;
export type ShaderStageFlags = ShaderStageFlagBit;
export type AccessFlags = AccessFlagBit;
export type DynamicStateFlags = DynamicStateFlagBit;
export type ClearFlags = ClearFlagBit;
export class Size {
x: number;
y: number;
z: number;
constructor(x?: number, y?: number, z?: number);
copy(info: Readonly): Size;
}
export class DeviceCaps {
maxVertexAttributes: number;
maxVertexUniformVectors: number;
maxFragmentUniformVectors: number;
maxTextureUnits: number;
maxImageUnits: number;
maxVertexTextureUnits: number;
maxColorRenderTargets: number;
maxShaderStorageBufferBindings: number;
maxShaderStorageBlockSize: number;
maxUniformBufferBindings: number;
maxUniformBlockSize: number;
maxTextureSize: number;
maxCubeMapTextureSize: number;
maxArrayTextureLayers: number;
max3DTextureSize: number;
uboOffsetAlignment: number;
maxComputeSharedMemorySize: number;
maxComputeWorkGroupInvocations: number;
maxComputeWorkGroupSize: Size;
maxComputeWorkGroupCount: Size;
supportQuery: boolean;
clipSpaceMinZ: number;
screenSpaceSignY: number;
clipSpaceSignY: number;
constructor(maxVertexAttributes?: number, maxVertexUniformVectors?: number, maxFragmentUniformVectors?: number, maxTextureUnits?: number, maxImageUnits?: number, maxVertexTextureUnits?: number, maxColorRenderTargets?: number, maxShaderStorageBufferBindings?: number, maxShaderStorageBlockSize?: number, maxUniformBufferBindings?: number, maxUniformBlockSize?: number, maxTextureSize?: number, maxCubeMapTextureSize?: number, maxArrayTextureLayers?: number, max3DTextureSize?: number, uboOffsetAlignment?: number, maxComputeSharedMemorySize?: number, maxComputeWorkGroupInvocations?: number, maxComputeWorkGroupSize?: Size, maxComputeWorkGroupCount?: Size, supportQuery?: boolean, clipSpaceMinZ?: number, screenSpaceSignY?: number, clipSpaceSignY?: number);
copy(info: Readonly): DeviceCaps;
}
export class DeviceOptions {
enableBarrierDeduce: boolean;
constructor(enableBarrierDeduce?: boolean);
copy(info: Readonly): DeviceOptions;
}
export class Offset {
x: number;
y: number;
z: number;
constructor(x?: number, y?: number, z?: number);
copy(info: Readonly): Offset;
}
export class Rect {
x: number;
y: number;
width: number;
height: number;
constructor(x?: number, y?: number, width?: number, height?: number);
copy(info: Readonly): Rect;
}
export class Extent {
width: number;
height: number;
depth: number;
constructor(width?: number, height?: number, depth?: number);
copy(info: Readonly): Extent;
}
export class TextureSubresLayers {
mipLevel: number;
baseArrayLayer: number;
layerCount: number;
constructor(mipLevel?: number, baseArrayLayer?: number, layerCount?: number);
copy(info: Readonly): TextureSubresLayers;
}
export class TextureSubresRange {
baseMipLevel: number;
levelCount: number;
baseArrayLayer: number;
layerCount: number;
constructor(baseMipLevel?: number, levelCount?: number, baseArrayLayer?: number, layerCount?: number);
copy(info: Readonly): TextureSubresRange;
}
export class TextureCopy {
srcSubres: TextureSubresLayers;
srcOffset: Offset;
dstSubres: TextureSubresLayers;
dstOffset: Offset;
extent: Extent;
constructor(srcSubres?: TextureSubresLayers, srcOffset?: Offset, dstSubres?: TextureSubresLayers, dstOffset?: Offset, extent?: Extent);
copy(info: Readonly): TextureCopy;
}
export class TextureBlit {
srcSubres: TextureSubresLayers;
srcOffset: Offset;
srcExtent: Extent;
dstSubres: TextureSubresLayers;
dstOffset: Offset;
dstExtent: Extent;
constructor(srcSubres?: TextureSubresLayers, srcOffset?: Offset, srcExtent?: Extent, dstSubres?: TextureSubresLayers, dstOffset?: Offset, dstExtent?: Extent);
copy(info: Readonly): TextureBlit;
}
export class BufferTextureCopy {
buffOffset: number;
buffStride: number;
buffTexHeight: number;
texOffset: Offset;
texExtent: Extent;
texSubres: TextureSubresLayers;
constructor(buffOffset?: number, buffStride?: number, buffTexHeight?: number, texOffset?: Offset, texExtent?: Extent, texSubres?: TextureSubresLayers);
copy(info: Readonly): BufferTextureCopy;
}
export class Viewport {
left: number;
top: number;
width: number;
height: number;
minDepth: number;
maxDepth: number;
constructor(left?: number, top?: number, width?: number, height?: number, minDepth?: number, maxDepth?: number);
copy(info: Readonly): Viewport;
reset(): void;
}
export class Color {
x: number;
y: number;
z: number;
w: number;
constructor(x?: number, y?: number, z?: number, w?: number);
copy(info: Readonly): Color;
set(x: number, y: number, z: number, w: number): Color;
reset(): void;
}
export class BindingMappingInfo {
maxBlockCounts: number[];
maxSamplerTextureCounts: number[];
maxSamplerCounts: number[];
maxTextureCounts: number[];
maxBufferCounts: number[];
maxImageCounts: number[];
maxSubpassInputCounts: number[];
setIndices: number[];
constructor(maxBlockCounts?: number[], maxSamplerTextureCounts?: number[], maxSamplerCounts?: number[], maxTextureCounts?: number[], maxBufferCounts?: number[], maxImageCounts?: number[], maxSubpassInputCounts?: number[], setIndices?: number[]);
copy(info: Readonly): BindingMappingInfo;
}
export class SwapchainInfo {
windowId: number;
windowHandle: HTMLCanvasElement;
vsyncMode: VsyncMode;
width: number;
height: number;
constructor(windowId?: number, windowHandle?: HTMLCanvasElement, vsyncMode?: VsyncMode, width?: number, height?: number);
copy(info: Readonly): SwapchainInfo;
}
export class DeviceInfo {
bindingMappingInfo: BindingMappingInfo;
constructor(bindingMappingInfo?: BindingMappingInfo);
copy(info: Readonly): DeviceInfo;
}
export class BufferInfo {
usage: BufferUsage;
memUsage: MemoryUsage;
size: number;
stride: number;
flags: BufferFlags;
constructor(usage?: BufferUsage, memUsage?: MemoryUsage, size?: number, stride?: number, flags?: BufferFlags);
copy(info: Readonly): BufferInfo;
}
export class BufferViewInfo {
buffer: Buffer;
offset: number;
range: number;
constructor(buffer?: Buffer, offset?: number, range?: number);
copy(info: Readonly): BufferViewInfo;
}
export class DrawInfo {
vertexCount: number;
firstVertex: number;
indexCount: number;
firstIndex: number;
vertexOffset: number;
instanceCount: number;
firstInstance: number;
constructor(vertexCount?: number, firstVertex?: number, indexCount?: number, firstIndex?: number, vertexOffset?: number, instanceCount?: number, firstInstance?: number);
copy(info: Readonly): DrawInfo;
}
export class DispatchInfo {
groupCountX: number;
groupCountY: number;
groupCountZ: number;
indirectBuffer: Buffer | null;
indirectOffset: number;
constructor(groupCountX?: number, groupCountY?: number, groupCountZ?: number, indirectBuffer?: Buffer | null, indirectOffset?: number);
copy(info: Readonly): DispatchInfo;
}
export class IndirectBuffer {
drawInfos: DrawInfo[];
constructor(drawInfos?: DrawInfo[]);
copy(info: Readonly): IndirectBuffer;
}
export class TextureInfo {
type: TextureType;
usage: TextureUsage;
format: Format;
width: number;
height: number;
flags: TextureFlags;
layerCount: number;
levelCount: number;
samples: SampleCount;
depth: number;
externalRes: number;
constructor(type?: TextureType, usage?: TextureUsage, format?: Format, width?: number, height?: number, flags?: TextureFlags, layerCount?: number, levelCount?: number, samples?: SampleCount, depth?: number, externalRes?: number);
copy(info: Readonly): TextureInfo;
}
export class TextureViewInfo {
texture: Texture;
type: TextureType;
format: Format;
baseLevel: number;
levelCount: number;
baseLayer: number;
layerCount: number;
constructor(texture?: Texture, type?: TextureType, format?: Format, baseLevel?: number, levelCount?: number, baseLayer?: number, layerCount?: number);
copy(info: Readonly): TextureViewInfo;
}
export class Uniform {
name: string;
type: Type;
count: number;
constructor(name?: string, type?: Type, count?: number);
copy(info: Readonly): Uniform;
}
export class UniformBlock {
set: number;
binding: number;
name: string;
members: Uniform[];
count: number;
flattened: number;
constructor(set?: number, binding?: number, name?: string, members?: Uniform[], count?: number, flattened?: number);
copy(info: Readonly): UniformBlock;
}
export class UniformSamplerTexture {
set: number;
binding: number;
name: string;
type: Type;
count: number;
flattened: number;
constructor(set?: number, binding?: number, name?: string, type?: Type, count?: number, flattened?: number);
copy(info: Readonly): UniformSamplerTexture;
}
export class UniformSampler {
set: number;
binding: number;
name: string;
count: number;
flattened: number;
constructor(set?: number, binding?: number, name?: string, count?: number, flattened?: number);
copy(info: Readonly): UniformSampler;
}
export class UniformTexture {
set: number;
binding: number;
name: string;
type: Type;
count: number;
flattened: number;
constructor(set?: number, binding?: number, name?: string, type?: Type, count?: number, flattened?: number);
copy(info: Readonly): UniformTexture;
}
export class UniformStorageImage {
set: number;
binding: number;
name: string;
type: Type;
count: number;
memoryAccess: MemoryAccess;
flattened: number;
constructor(set?: number, binding?: number, name?: string, type?: Type, count?: number, memoryAccess?: MemoryAccess, flattened?: number);
copy(info: Readonly): UniformStorageImage;
}
export class UniformStorageBuffer {
set: number;
binding: number;
name: string;
count: number;
memoryAccess: MemoryAccess;
flattened: number;
constructor(set?: number, binding?: number, name?: string, count?: number, memoryAccess?: MemoryAccess, flattened?: number);
copy(info: Readonly): UniformStorageBuffer;
}
export class UniformInputAttachment {
set: number;
binding: number;
name: string;
count: number;
flattened: number;
constructor(set?: number, binding?: number, name?: string, count?: number, flattened?: number);
copy(info: Readonly): UniformInputAttachment;
}
export class ShaderStage {
stage: ShaderStageFlagBit;
source: string;
constructor(stage?: ShaderStageFlagBit, source?: string);
copy(info: Readonly): ShaderStage;
}
export class Attribute {
name: string;
format: Format;
isNormalized: boolean;
stream: number;
isInstanced: boolean;
location: number;
constructor(name?: string, format?: Format, isNormalized?: boolean, stream?: number, isInstanced?: boolean, location?: number);
copy(info: Readonly): Attribute;
}
export class ShaderInfo {
name: string;
stages: ShaderStage[];
attributes: Attribute[];
blocks: UniformBlock[];
buffers: UniformStorageBuffer[];
samplerTextures: UniformSamplerTexture[];
samplers: UniformSampler[];
textures: UniformTexture[];
images: UniformStorageImage[];
subpassInputs: UniformInputAttachment[];
constructor(name?: string, stages?: ShaderStage[], attributes?: Attribute[], blocks?: UniformBlock[], buffers?: UniformStorageBuffer[], samplerTextures?: UniformSamplerTexture[], samplers?: UniformSampler[], textures?: UniformTexture[], images?: UniformStorageImage[], subpassInputs?: UniformInputAttachment[]);
copy(info: Readonly): ShaderInfo;
}
export class InputAssemblerInfo {
attributes: Attribute[];
vertexBuffers: Buffer[];
indexBuffer: Buffer | null;
indirectBuffer: Buffer | null;
constructor(attributes?: Attribute[], vertexBuffers?: Buffer[], indexBuffer?: Buffer | null, indirectBuffer?: Buffer | null);
copy(info: Readonly): InputAssemblerInfo;
}
export class ColorAttachment {
format: Format;
sampleCount: SampleCount;
loadOp: LoadOp;
storeOp: StoreOp;
barrier: GeneralBarrier;
constructor(format?: Format, sampleCount?: SampleCount, loadOp?: LoadOp, storeOp?: StoreOp, barrier?: GeneralBarrier);
copy(info: Readonly): ColorAttachment;
}
export class DepthStencilAttachment {
format: Format;
sampleCount: SampleCount;
depthLoadOp: LoadOp;
depthStoreOp: StoreOp;
stencilLoadOp: LoadOp;
stencilStoreOp: StoreOp;
barrier: GeneralBarrier;
constructor(format?: Format, sampleCount?: SampleCount, depthLoadOp?: LoadOp, depthStoreOp?: StoreOp, stencilLoadOp?: LoadOp, stencilStoreOp?: StoreOp, barrier?: GeneralBarrier);
copy(info: Readonly): DepthStencilAttachment;
}
export class SubpassInfo {
inputs: number[];
colors: number[];
resolves: number[];
preserves: number[];
depthStencil: number;
depthStencilResolve: number;
depthResolveMode: ResolveMode;
stencilResolveMode: ResolveMode;
constructor(inputs?: number[], colors?: number[], resolves?: number[], preserves?: number[], depthStencil?: number, depthStencilResolve?: number, depthResolveMode?: ResolveMode, stencilResolveMode?: ResolveMode);
copy(info: Readonly): SubpassInfo;
}
export class SubpassDependency {
srcSubpass: number;
dstSubpass: number;
generalBarrier: GeneralBarrier;
prevAccesses: AccessFlags[];
nextAccesses: AccessFlags[];
constructor(srcSubpass?: number, dstSubpass?: number, generalBarrier?: GeneralBarrier, prevAccesses?: AccessFlags[], nextAccesses?: AccessFlags[]);
copy(info: Readonly): SubpassDependency;
}
export class RenderPassInfo {
colorAttachments: ColorAttachment[];
depthStencilAttachment: DepthStencilAttachment;
depthStencilResolveAttachment: DepthStencilAttachment;
subpasses: SubpassInfo[];
dependencies: SubpassDependency[];
constructor(colorAttachments?: ColorAttachment[], depthStencilAttachment?: DepthStencilAttachment, depthStencilResolveAttachment?: DepthStencilAttachment, subpasses?: SubpassInfo[], dependencies?: SubpassDependency[]);
copy(info: Readonly): RenderPassInfo;
}
export class GeneralBarrierInfo {
prevAccesses: AccessFlags;
nextAccesses: AccessFlags;
type: BarrierType;
constructor(prevAccesses?: AccessFlags, nextAccesses?: AccessFlags, type?: BarrierType);
copy(info: Readonly): GeneralBarrierInfo;
}
export class TextureBarrierInfo {
prevAccesses: AccessFlags;
nextAccesses: AccessFlags;
type: BarrierType;
baseMipLevel: number;
levelCount: number;
baseSlice: number;
sliceCount: number;
discardContents: boolean;
srcQueue: Queue | null;
dstQueue: Queue | null;
constructor(prevAccesses?: AccessFlags, nextAccesses?: AccessFlags, type?: BarrierType, baseMipLevel?: number, levelCount?: number, baseSlice?: number, sliceCount?: number, discardContents?: boolean, srcQueue?: Queue | null, dstQueue?: Queue | null);
copy(info: Readonly): TextureBarrierInfo;
}
export class BufferBarrierInfo {
prevAccesses: AccessFlags;
nextAccesses: AccessFlags;
type: BarrierType;
offset: number;
size: number;
discardContents: boolean;
srcQueue: Queue | null;
dstQueue: Queue | null;
constructor(prevAccesses?: AccessFlags, nextAccesses?: AccessFlags, type?: BarrierType, offset?: number, size?: number, discardContents?: boolean, srcQueue?: Queue | null, dstQueue?: Queue | null);
copy(info: Readonly): BufferBarrierInfo;
}
export class FramebufferInfo {
renderPass: RenderPass;
colorTextures: Texture[];
depthStencilTexture: Texture | null;
depthStencilResolveTexture: Texture | null;
constructor(renderPass?: RenderPass, colorTextures?: Texture[], depthStencilTexture?: Texture | null, depthStencilResolveTexture?: Texture | null);
copy(info: Readonly): FramebufferInfo;
}
export class DescriptorSetLayoutBinding {
binding: number;
descriptorType: DescriptorType;
count: number;
stageFlags: ShaderStageFlags;
immutableSamplers: Sampler[];
constructor(binding?: number, descriptorType?: DescriptorType, count?: number, stageFlags?: ShaderStageFlags, immutableSamplers?: Sampler[]);
copy(info: Readonly): DescriptorSetLayoutBinding;
}
export class DescriptorSetLayoutInfo {
bindings: DescriptorSetLayoutBinding[];
constructor(bindings?: DescriptorSetLayoutBinding[]);
copy(info: Readonly): DescriptorSetLayoutInfo;
reset(): void;
}
export class DescriptorSetInfo {
layout: DescriptorSetLayout;
constructor(layout?: DescriptorSetLayout);
copy(info: Readonly): DescriptorSetInfo;
}
export class PipelineLayoutInfo {
setLayouts: DescriptorSetLayout[];
constructor(setLayouts?: DescriptorSetLayout[]);
copy(info: Readonly): PipelineLayoutInfo;
}
export class InputState {
attributes: Attribute[];
constructor(attributes?: Attribute[]);
copy(info: Readonly): InputState;
}
export class CommandBufferInfo {
queue: Queue;
type: CommandBufferType;
constructor(queue?: Queue, type?: CommandBufferType);
copy(info: Readonly): CommandBufferInfo;
}
export class QueueInfo {
type: QueueType;
constructor(type?: QueueType);
copy(info: Readonly): QueueInfo;
}
export class QueryPoolInfo {
type: QueryType;
maxQueryObjects: number;
forceWait: boolean;
constructor(type?: QueryType, maxQueryObjects?: number, forceWait?: boolean);
copy(info: Readonly): QueryPoolInfo;
}
export class FormatInfo {
readonly name: string;
readonly size: number;
readonly count: number;
readonly type: FormatType;
readonly hasAlpha: boolean;
readonly hasDepth: boolean;
readonly hasStencil: boolean;
readonly isCompressed: boolean;
constructor(name?: string, size?: number, count?: number, type?: FormatType, hasAlpha?: boolean, hasDepth?: boolean, hasStencil?: boolean, isCompressed?: boolean);
}
export class MemoryStatus {
bufferSize: number;
textureSize: number;
constructor(bufferSize?: number, textureSize?: number);
copy(info: Readonly): MemoryStatus;
}
export class DynamicStencilStates {
writeMask: number;
compareMask: number;
reference: number;
constructor(writeMask?: number, compareMask?: number, reference?: number);
copy(info: Readonly): DynamicStencilStates;
}
export class DynamicStates {
viewport: Viewport;
scissor: Rect;
blendConstant: Color;
lineWidth: number;
depthBiasConstant: number;
depthBiasClamp: number;
depthBiasSlope: number;
depthMinBounds: number;
depthMaxBounds: number;
stencilStatesFront: DynamicStencilStates;
stencilStatesBack: DynamicStencilStates;
constructor(viewport?: Viewport, scissor?: Rect, blendConstant?: Color, lineWidth?: number, depthBiasConstant?: number, depthBiasClamp?: number, depthBiasSlope?: number, depthMinBounds?: number, depthMaxBounds?: number, stencilStatesFront?: DynamicStencilStates, stencilStatesBack?: DynamicStencilStates);
copy(info: Readonly): DynamicStates;
}
/**
* ========================= !DO NOT CHANGE THE ABOVE SECTION MANUALLY! =========================
* The above section is auto-generated from native/cocos/renderer/core/gfx/GFXDef-common.h
* by the script native/tools/gfx-define-generator/generate.js.
* Changes to these public interfaces should be made there first and synced back.
* ========================= !DO NOT CHANGE THE ABOVE SECTION MANUALLY! =========================
*/
/**
* @en GFX base object.
* @zh GFX 基类对象。
*/
export class GFXObject extends __private._cocos_core_data_gc_object__GCObject {
get objectType(): ObjectType;
get objectID(): number;
get typedID(): number;
protected _objectType: ObjectType;
protected _objectID: number;
protected _typedID: number;
constructor(objectType: ObjectType);
}
export interface ISwapchainTextureInfo {
swapchain: Swapchain;
format: Format;
width: number;
height: number;
}
export enum AttributeName {
ATTR_POSITION = "a_position",
ATTR_NORMAL = "a_normal",
ATTR_TANGENT = "a_tangent",
ATTR_BITANGENT = "a_bitangent",
ATTR_WEIGHTS = "a_weights",
ATTR_JOINTS = "a_joints",
ATTR_COLOR = "a_color",
ATTR_COLOR1 = "a_color1",
ATTR_COLOR2 = "a_color2",
ATTR_TEX_COORD = "a_texCoord",
ATTR_TEX_COORD1 = "a_texCoord1",
ATTR_TEX_COORD2 = "a_texCoord2",
ATTR_TEX_COORD3 = "a_texCoord3",
ATTR_TEX_COORD4 = "a_texCoord4",
ATTR_TEX_COORD5 = "a_texCoord5",
ATTR_TEX_COORD6 = "a_texCoord6",
ATTR_TEX_COORD7 = "a_texCoord7",
ATTR_TEX_COORD8 = "a_texCoord8",
ATTR_BATCH_ID = "a_batch_id",
ATTR_BATCH_UV = "a_batch_uv"
}
export const FormatInfos: readonly FormatInfo[];
export const DESCRIPTOR_BUFFER_TYPE: number;
export const DESCRIPTOR_SAMPLER_TYPE: number;
export const DESCRIPTOR_DYNAMIC_TYPE: number;
export const DRAW_INFO_SIZE = 28;
export type BufferSource = ArrayBuffer | IndirectBuffer;
export interface FormatAlignment {
width: number;
height: number;
}
/**
* @en GFX Device.
* @zh GFX 设备。
*/
export abstract class Device {
/**
* @en Current rendering API.
* @zh 当前 GFX 使用的渲染 API。
*/
get gfxAPI(): API;
/**
* @en GFX default queue.
* @zh GFX 默认队列。
*/
get queue(): Queue;
/**
* @en GFX default command buffer.
* @zh GFX 默认命令缓冲。
*/
get commandBuffer(): CommandBuffer;
/**
* @en Renderer description.
* @zh 渲染器描述。
*/
get renderer(): string;
/**
* @en Vendor description.
* @zh 厂商描述。
*/
get vendor(): string;
/**
* @en Number of draw calls currently recorded.
* @zh 绘制调用次数。
*/
get numDrawCalls(): number;
/**
* @en Number of instances currently recorded.
* @zh 绘制 Instance 数量。
*/
get numInstances(): number;
/**
* @en Number of triangles currently recorded.
* @zh 渲染三角形数量。
*/
get numTris(): number;
/**
* @en Total memory size currently allocated.
* @zh 内存状态。
*/
get memoryStatus(): MemoryStatus;
/**
* @en Current device capabilities.
* @zh 当前设备能力数据。
*/
get capabilities(): DeviceCaps;
/**
* @en Current device binding mappings.
* @zh 当前设备的绑定槽位映射关系。
*/
get bindingMappingInfo(): BindingMappingInfo;
protected _gfxAPI: API;
protected _renderer: string;
protected _vendor: string;
protected _features: boolean[];
protected _formatFeatures: FormatFeatureBit[];
protected _queue: Queue | null;
protected _cmdBuff: CommandBuffer | null;
protected _numDrawCalls: number;
protected _numInstances: number;
protected _numTris: number;
protected _memoryStatus: MemoryStatus;
protected _caps: DeviceCaps;
protected _bindingMappingInfo: BindingMappingInfo;
protected _samplers: Map;
protected _generalBarrierss: Map;
protected _textureBarriers: Map;
protected _bufferBarriers: Map;
static canvas: HTMLCanvasElement;
abstract initialize(info: Readonly): boolean;
abstract destroy(): void;
/**
* @en Acquire next swapchain image.
* @zh 获取下一个交换链缓冲。
*/
abstract acquire(swapchains: Readonly): void;
/**
* @en Present current swapchain image.
* @zh 上屏当前交换链缓冲。
*/
abstract present(): void;
/**
* @en Flush the specified command buffers.
* @zh 实际录制指定的命令缓冲。
*/
abstract flushCommands(cmdBuffs: Readonly): void;
/**
* @en Create command buffer.
* @zh 创建命令缓冲。
* @param info GFX command buffer description info.
*/
abstract createCommandBuffer(info: Readonly): CommandBuffer;
/**
* @en Create swapchain.
* @zh 创建交换链。
* @param info GFX swapchain description info.
*/
abstract createSwapchain(info: Readonly): Swapchain;
/**
* @en Create buffer.
* @zh 创建缓冲。
* @param info GFX buffer description info.
*/
abstract createBuffer(info: Readonly | BufferViewInfo): Buffer;
/**
* @en Create texture.
* @zh 创建纹理。
* @param info GFX texture description info.
*/
abstract createTexture(info: Readonly | TextureViewInfo): Texture;
/**
* @en Create descriptor sets.
* @zh 创建描述符集组。
* @param info GFX descriptor sets description info.
*/
abstract createDescriptorSet(info: Readonly): DescriptorSet;
/**
* @en Create shader.
* @zh 创建着色器。
* @param info GFX shader description info.
*/
abstract createShader(info: Readonly): Shader;
/**
* @en Create input assembler.
* @zh 创建纹理。
* @param info GFX input assembler description info.
*/
abstract createInputAssembler(info: Readonly): InputAssembler;
/**
* @en Create render pass.
* @zh 创建渲染过程。
* @param info GFX render pass description info.
*/
abstract createRenderPass(info: Readonly): RenderPass;
/**
* @en Create frame buffer.
* @zh 创建帧缓冲。
* @param info GFX frame buffer description info.
*/
abstract createFramebuffer(info: Readonly): Framebuffer;
/**
* @en Create descriptor set layout.
* @zh 创建描述符集布局。
* @param info GFX descriptor set layout description info.
*/
abstract createDescriptorSetLayout(info: Readonly): DescriptorSetLayout;
/**
* @en Create pipeline layout.
* @zh 创建管线布局。
* @param info GFX pipeline layout description info.
*/
abstract createPipelineLayout(info: Readonly): PipelineLayout;
/**
* @en Create pipeline state.
* @zh 创建管线状态。
* @param info GFX pipeline state description info.
*/
abstract createPipelineState(info: Readonly): PipelineState;
/**
* @en Create queue.
* @zh 创建队列。
* @param info GFX queue description info.
*/
abstract createQueue(info: Readonly): Queue;
/**
* @en Create sampler.
* @zh 创建采样器。
* @param info GFX sampler description info.
*/
abstract getSampler(info: Readonly): Sampler;
/**
* @en Get swapchains.
* @zh 获取交换链列表。
*/
abstract getSwapchains(): Readonly;
/**
* @en Create global barrier.
* @zh 创建全局内存屏障。
* @param info GFX global barrier description info.
*/
abstract getGeneralBarrier(info: Readonly): GeneralBarrier;
/**
* @en Create texture barrier.
* @zh 创建贴图内存屏障。
* @param info GFX texture barrier description info.
*/
abstract getTextureBarrier(info: Readonly): TextureBarrier;
/**
* @en Create buffer barrier.
* @zh 创建buffer内存屏障。
* @param info GFX buffer barrier description info.
*/
abstract getBufferBarrier(info: Readonly): __private._cocos_gfx_base_states_buffer_barrier__BufferBarrier;
/**
* @en Copy buffers to texture.
* @zh 拷贝缓冲到纹理。
* @param buffers The buffers to be copied.
* @param texture The texture to copy to.
* @param regions The region descriptions.
*/
abstract copyBuffersToTexture(buffers: Readonly, texture: Texture, regions: Readonly): void;
/**
* @en Copy texture to buffers
* @zh 拷贝纹理到缓冲
* @param texture The texture to be copied.
* @param buffers The buffer to copy to.
* @param regions The region descriptions
*/
abstract copyTextureToBuffers(texture: Readonly, buffers: ArrayBufferView[], regions: Readonly): void;
/**
* @en Copy texture images to texture.
* @zh 拷贝图像到纹理。
* @param texImages The texture to be copied.
* @param texture The texture to copy to.
* @param regions The region descriptions.
*/
abstract copyTexImagesToTexture(texImages: Readonly, texture: Texture, regions: Readonly): void;
/**
* @en Whether the device has specific feature.
* @zh 是否具备特性。
* @param feature The GFX feature to be queried.
*/
hasFeature(feature: Feature): boolean;
/**
* @en The extent a specific format is supported by the backend.
* @zh 后端对特定格式的支持程度。
* @param format The GFX format to be queried.
*/
getFormatFeatures(format: Format): FormatFeature;
/**
* @en Enable automatically barrier deduction GFX inside, no effect on web.
* @zh 是否开启自动GFX内部barrier推导，web无影响。
* @param format The GFX format to be queried.
*/
enableAutoBarrier(en: boolean): void;
/**
* @en Get maximum supported sample count.
* @zh 获取最大可支持的 Samples 参数
* @param format The GFX texture format.
* @param usage The GFX texture usage.
* @param flags The GFX texture create flags.
*/
getMaxSampleCount(format: Format, usage: TextureUsage, flags: TextureFlags): SampleCount;
}
export class DefaultResource {
constructor(device: Device);
getTexture(type: TextureType): Texture | null;
}
/**
* @en GFX Swapchain.
* @zh GFX 交换链。
*/
export abstract class Swapchain extends GFXObject {
/**
* @en The color texture of this swapchain.
* @zh 当前交换链的颜色缓冲。
*/
get colorTexture(): Texture;
/**
* @en The depth stencil texture of this swapchain.
* @zh 当前交换链的深度模板缓冲。
*/
get depthStencilTexture(): Texture;
/**
* @en The surface transform to be applied in projection matrices.
* @zh 需要在投影矩阵中应用的表面变换。
*/
get surfaceTransform(): SurfaceTransform;
get width(): number;
get height(): number;
protected _transform: SurfaceTransform;
protected _colorTexture: Texture;
protected _depthStencilTexture: Texture;
constructor();
abstract initialize(info: Readonly): void;
abstract resize(width: number, height: number, surfaceTransform: SurfaceTransform): void;
abstract destroy(): void;
}
/**
* @en GFX frame buffer.
* @zh GFX 帧缓冲。
*/
export abstract class Framebuffer extends GFXObject {
/**
* @en Get current render pass.
* @zh GFX 渲染过程。
*/
get renderPass(): RenderPass;
/**
* @en Get current color views.
* @zh 颜色纹理视图数组。
*/
get colorTextures(): (Texture | null)[];
/**
* @en Get current depth stencil views.
* @zh 深度模板纹理视图。
*/
get depthStencilTexture(): Texture | null;
get width(): number;
get height(): number;
protected _renderPass: RenderPass | null;
protected _colorTextures: (Texture | null)[];
protected _depthStencilTexture: Texture | null;
protected _width: number;
protected _height: number;
constructor();
abstract initialize(info: Readonly): void;
abstract destroy(): void;
}
/**
* @en GFX input assembler.
* @zh GFX 输入汇集器。
*/
export abstract class InputAssembler extends GFXObject {
/**
* @en Get current attributes.
* @zh 顶点属性数组。
*/
get attributes(): Attribute[];
/**
* @en Get current vertex buffers.
* @zh 顶点缓冲数组。
*/
get vertexBuffers(): Buffer[];
/**
* @en Get current index buffer.
* @zh 索引缓冲。
*/
get indexBuffer(): Buffer | null;
/**
* @en Get the indirect buffer, if present.
* @zh 间接绘制缓冲。
*/
get indirectBuffer(): Buffer | null;
/**
* @en Get hash of current attributes.
* @zh 获取顶点属性数组的哈希值。
*/
get attributesHash(): number;
/**
* @en Get current vertex count.
* @zh 顶点数量。
*/
set vertexCount(count: number);
get vertexCount(): number;
/**
* @en Get starting vertex.
* @zh 起始顶点。
*/
set firstVertex(first: number);
get firstVertex(): number;
/**
* @en Get current index count.
* @zh 索引数量。
*/
set indexCount(count: number);
get indexCount(): number;
/**
* @en Get starting index.
* @zh 起始索引。
*/
set firstIndex(first: number);
get firstIndex(): number;
/**
* @en Get current vertex offset.
* @zh 顶点偏移量。
*/
set vertexOffset(offset: number);
get vertexOffset(): number;
/**
* @en Get current instance count.
* @zh 实例数量。
*/
set instanceCount(count: number);
get instanceCount(): number;
/**
* @en Get starting instance.
* @zh 起始实例。
*/
set firstInstance(first: number);
get firstInstance(): number;
/**
* @en set the draw range
* @zh 设置渲染范围
*/
set drawInfo(info: DrawInfo);
/**
* @en get the draw range
* @zh 获取渲染范围
*/
get drawInfo(): DrawInfo;
protected _attributes: Attribute[];
protected _attributesHash: number;
protected _vertexBuffers: Buffer[];
protected _indexBuffer: Buffer | null;
protected _indirectBuffer: Buffer | null;
protected _drawInfo: DrawInfo;
constructor();
/**
* @en Get the specified vertex buffer.
* @zh 获取顶点缓冲。
* @param stream The stream index of the vertex buffer.
*/
getVertexBuffer(stream?: number): Buffer | null;
protected computeAttributesHash(): number;
abstract initialize(info: Readonly): void;
abstract destroy(): void;
}
/**
* @en GFX descriptor sets layout.
* @zh GFX 描述符集布局。
*/
export abstract class DescriptorSetLayout extends GFXObject {
get bindings(): DescriptorSetLayoutBinding[];
get bindingIndices(): number[];
get descriptorIndices(): number[];
protected _bindings: DescriptorSetLayoutBinding[];
protected _bindingIndices: number[];
protected _descriptorIndices: number[];
constructor();
abstract initialize(info: Readonly): void;
abstract destroy(): void;
}
/**
* @en GFX pipeline layout.
* @zh GFX 管线布局。
*/
export abstract class PipelineLayout extends GFXObject {
get setLayouts(): DescriptorSetLayout[];
protected _setLayouts: DescriptorSetLayout[];
constructor();
abstract initialize(info: Readonly): void;
abstract destroy(): void;
}
/**
* @en GFX blend state.
* @zh GFX 混合状态。
*/
export class BlendState {
isA2C: boolean;
isIndepend: boolean;
blendColor: Color;
targets: BlendTarget[];
get native(): BlendState;
constructor(isA2C?: boolean, isIndepend?: boolean, blendColor?: Color, targets?: BlendTarget[]);
/**
* @en Should use this function to set target, or it will not work
* on native platforms, as native can not support this feature,
* such as `blendState[i] = target;`.
*
* @param index The index to set target.
* @param target The target to be set.
*/
setTarget(index: number, target: BlendTarget): void;
reset(): void;
destroy(): void;
}
/**
* @en GFX blend target.
* @zh GFX 混合目标。
*/
export class BlendTarget {
blend: boolean;
blendSrc: BlendFactor;
blendDst: BlendFactor;
blendEq: BlendOp;
blendSrcAlpha: BlendFactor;
blendDstAlpha: BlendFactor;
blendAlphaEq: BlendOp;
blendColorMask: ColorMask;
constructor(blend?: boolean, blendSrc?: BlendFactor, blendDst?: BlendFactor, blendEq?: BlendOp, blendSrcAlpha?: BlendFactor, blendDstAlpha?: BlendFactor, blendAlphaEq?: BlendOp, blendColorMask?: ColorMask);
reset(): void;
assign(target: BlendTarget): void;
destroy(): void;
}
/**
* @en GFX rasterizer state.
* @zh GFX 光栅化状态。
*/
export class RasterizerState {
isDiscard: boolean;
polygonMode: PolygonMode;
shadeModel: ShadeModel;
cullMode: CullMode;
isFrontFaceCCW: boolean;
depthBiasEnabled: boolean;
depthBias: number;
depthBiasClamp: number;
depthBiasSlop: number;
isDepthClip: boolean;
isMultisample: boolean;
lineWidth: number;
get native(): RasterizerState;
constructor(isDiscard?: boolean, polygonMode?: PolygonMode, shadeModel?: ShadeModel, cullMode?: CullMode, isFrontFaceCCW?: boolean, depthBiasEnabled?: boolean, depthBias?: number, depthBiasClamp?: number, depthBiasSlop?: number, isDepthClip?: boolean, isMultisample?: boolean, lineWidth?: number);
reset(): void;
assign(rs: RasterizerState): void;
destroy(): void;
}
/**
* @en GFX depth stencil state.
* @zh GFX 深度模板状态。
*/
export class DepthStencilState {
depthTest: boolean;
depthWrite: boolean;
depthFunc: ComparisonFunc;
stencilTestFront: boolean;
stencilFuncFront: ComparisonFunc;
stencilReadMaskFront: number;
stencilWriteMaskFront: number;
stencilFailOpFront: StencilOp;
stencilZFailOpFront: StencilOp;
stencilPassOpFront: StencilOp;
stencilRefFront: number;
stencilTestBack: boolean;
stencilFuncBack: ComparisonFunc;
stencilReadMaskBack: number;
stencilWriteMaskBack: number;
stencilFailOpBack: StencilOp;
stencilZFailOpBack: StencilOp;
stencilPassOpBack: StencilOp;
stencilRefBack: number;
get native(): DepthStencilState;
constructor(depthTest?: boolean, depthWrite?: boolean, depthFunc?: ComparisonFunc, stencilTestFront?: boolean, stencilFuncFront?: ComparisonFunc, stencilReadMaskFront?: number, stencilWriteMaskFront?: number, stencilFailOpFront?: StencilOp, stencilZFailOpFront?: StencilOp, stencilPassOpFront?: StencilOp, stencilRefFront?: number, stencilTestBack?: boolean, stencilFuncBack?: ComparisonFunc, stencilReadMaskBack?: number, stencilWriteMaskBack?: number, stencilFailOpBack?: StencilOp, stencilZFailOpBack?: StencilOp, stencilPassOpBack?: StencilOp, stencilRefBack?: number);
reset(): void;
assign(dss: DepthStencilState): void;
destroy(): void;
}
export class PipelineStateInfo {
shader: Shader;
pipelineLayout: PipelineLayout;
renderPass: RenderPass;
inputState: InputState;
rasterizerState: RasterizerState;
depthStencilState: DepthStencilState;
blendState: BlendState;
primitive: PrimitiveMode;
dynamicStates: DynamicStateFlags;
bindPoint: PipelineBindPoint;
constructor(shader?: Shader, pipelineLayout?: PipelineLayout, renderPass?: RenderPass, inputState?: InputState, rasterizerState?: RasterizerState, depthStencilState?: DepthStencilState, blendState?: BlendState, primitive?: PrimitiveMode, dynamicStates?: DynamicStateFlags, bindPoint?: PipelineBindPoint);
}
/**
* @en GFX pipeline state.
* @zh GFX 管线状态。
*/
export abstract class PipelineState extends GFXObject {
/**
* @en Get current shader.
* @zh GFX 着色器。
*/
get shader(): Shader;
/**
* @en Get current pipeline layout.
* @zh GFX 管线布局。
*/
get pipelineLayout(): PipelineLayout;
/**
* @en Get current primitve mode.
* @zh GFX 图元模式。
*/
get primitive(): PrimitiveMode;
/**
* @en Get current rasterizer state.
* @zh GFX 光栅化状态。
*/
get rasterizerState(): RasterizerState;
/**
* @en Get current depth stencil state.
* @zh GFX 深度模板状态。
*/
get depthStencilState(): DepthStencilState;
/**
* @en Get current blend state.
* @zh GFX 混合状态。
*/
get blendState(): BlendState;
/**
* @en Get current input state.
* @zh GFX 输入状态。
*/
get inputState(): InputState;
/**
* @en Get current dynamic states.
* @zh GFX 动态状态数组。
*/
get dynamicStates(): DynamicStateFlags;
/**
* @en Get current render pass.
* @zh GFX 渲染过程。
*/
get renderPass(): RenderPass;
protected _shader: Shader | null;
protected _pipelineLayout: PipelineLayout | null;
protected _primitive: PrimitiveMode;
protected _is: InputState | null;
protected _rs: RasterizerState;
protected _dss: DepthStencilState;
protected _bs: BlendState;
protected _dynamicStates: DynamicStateFlags;
protected _renderPass: RenderPass | null;
constructor();
abstract initialize(info: Readonly): void;
abstract destroy(): void;
}
/**
* @en GFX Queue.
* @zh GFX 队列。
*/
export abstract class Queue extends GFXObject {
/**
* @en Get current type.
* @zh 队列类型。
*/
get type(): number;
protected _type: QueueType;
constructor();
abstract initialize(info: Readonly): void;
abstract destroy(): void;
/**
* @en Submit command buffers.
* @zh 提交命令缓冲数组。
* @param cmdBuffs The command buffers to be submitted.
* @param fence The syncing fence.
*/
abstract submit(cmdBuffs: Readonly): void;
}
/**
* @en GFX render pass.
* @zh GFX 渲染过程。
*/
export abstract class RenderPass extends GFXObject {
protected _colorInfos: ColorAttachment[];
protected _depthStencilInfo: DepthStencilAttachment | null;
protected _subpasses: SubpassInfo[];
protected _hash: number;
get colorAttachments(): Readonly;
get depthStencilAttachment(): Readonly | null;
get subPasses(): Readonly;
get hash(): number;
constructor();
protected computeHash(): number;
abstract initialize(info: Readonly): void;
abstract destroy(): void;
}
/**
* @en GFX shader.
* @zh GFX 着色器。
*/
export abstract class Shader extends GFXObject {
get name(): string;
get attributes(): Attribute[];
get blocks(): UniformBlock[];
get samplers(): UniformSampler[];
get stages(): ShaderStage[];
protected _name: string;
protected _stages: ShaderStage[];
protected _attributes: Attribute[];
protected _blocks: UniformBlock[];
protected _samplers: UniformSampler[];
constructor();
abstract initialize(info: Readonly): void;
abstract destroy(): void;
}
/**
* @en GFX texture.
* @zh GFX 纹理。
*/
export abstract class Texture extends GFXObject {
/**
* @en Get texture type.
* @zh 纹理类型。
*/
get type(): TextureType;
/**
* @en Get texture usage.
* @zh 纹理使用方式。
*/
get usage(): TextureUsage;
/**
* @en Get texture format.
* @zh 纹理格式。
*/
get format(): Format;
/**
* @en Get texture width.
* @zh 纹理宽度。
*/
get width(): number;
/**
* @en Get texture height.
* @zh 纹理高度。
*/
get height(): number;
/**
* @en Get texture depth.
* @zh 纹理深度。
*/
get depth(): number;
/**
* @en Get texture array layer.
* @zh 纹理数组层数。
*/
get layerCount(): number;
/**
* @en Get texture mip level.
* @zh 纹理 mip 层级数。
*/
get levelCount(): number;
/**
* @en Get texture samples.
* @zh 纹理采样数。
*/
get samples(): SampleCount;
/**
* @en Get texture flags.
* @zh 纹理标识位。
*/
get flags(): TextureFlags;
/**
* @en Get texture size.
* @zh 纹理大小。
*/
get size(): number;
/**
* @en Get texture info.
* @zh 纹理信息。
*/
get info(): Readonly;
/**
* @en Get view info.
* @zh 纹理视图信息。
*/
get viewInfo(): Readonly;
/**
* @en Get texture type.
* @zh 是否为纹理视图。
*/
get isTextureView(): boolean;
protected _info: TextureInfo;
protected _viewInfo: TextureViewInfo;
protected _isPowerOf2: boolean;
protected _isTextureView: boolean;
protected _size: number;
constructor();
abstract initialize(info: Readonly | Readonly): void;
abstract destroy(): void;
abstract getGLTextureHandle(): number;
/**
* @en Resize texture.
* @zh 重置纹理大小。
* @param width The new width.
* @param height The new height.
*/
abstract resize(width: number, height: number): void;
static getLevelCount(width: number, height: number): number;
}
/**
* @en GFX global barrier.
* @zh GFX 全局内存屏障。
*/
export class GeneralBarrier extends GFXObject {
get info(): Readonly;
get hash(): number;
protected _info: GeneralBarrierInfo;
protected _hash: number;
constructor(info: Readonly, hash: number);
static computeHash(info: Readonly): number;
}
/**
* @en GFX texture barrier.
* @zh GFX 贴图内存屏障。
*/
export class TextureBarrier extends GFXObject {
get info(): Readonly;
get hash(): number;
protected _info: TextureBarrierInfo;
protected _hash: number;
constructor(info: Readonly, hash: number);
static computeHash(info: Readonly): number;
}
/**
* @en
* Sets the renderer type, only useful on web
*
* @zh
* 渲染模式。
* 设置渲染器类型，仅适用于 web 端
* @internal
*/
export enum LegacyRenderMode {
/**
* @en
* Automatically chosen by engine.
* @zh
* 通过引擎自动选择。
*/
AUTO = 0,
/**
* @en
* Forced to use canvas renderer.
* @zh
* 强制使用 canvas 渲染。
*/
CANVAS = 1,
/**
* @en
* Forced to use WebGL renderer, but this will be ignored on mobile browsers.
* @zh
* 强制使用 WebGL 渲染，但是在部分 Android 浏览器中这个选项会被忽略。
*/
WEBGL = 2,
/**
* @en
* Use Headless Renderer, which is useful in test or server env, only for internal use by cocos team for now
* @zh
* 使用空渲染器，可以用于测试和服务器端环境，目前暂时用于 Cocos 内部测试使用。
*/
HEADLESS = 3
}
/**
* @internal
*/
export enum RenderType {
UNKNOWN = "Bad expression <-1>",
CANVAS = 0,
WEBGL = 1,
OPENGL = 2,
HEADLESS = 3
}
/**
* @internal
*/
export class DeviceManager {
get gfxDevice(): Device;
get swapchain(): Swapchain;
init(canvas: HTMLCanvasElement | null, bindingMappingInfo: BindingMappingInfo): void;
}
/**
* @internal
*/
export const deviceManager: DeviceManager;
}
export namespace renderer {
export function createIA(device: gfx.Device, data: primitives.IGeometry): gfx.InputAssembler | null;
export const addStage: (name: any) => void;
export interface IProgramInfo extends EffectAsset.IShaderInfo {
effectName: string;
defines: __private._cocos_render_scene_core_program_lib__IDefineRecord[];
constantMacros: string;
uber: boolean;
}
export interface ITemplateInfo {
gfxAttributes: gfx.Attribute[];
shaderInfo: gfx.ShaderInfo;
blockSizes: number[];
setLayouts: gfx.DescriptorSetLayout[];
pipelineLayout: gfx.PipelineLayout;
handleMap: Record;
bindings: gfx.DescriptorSetLayoutBinding[];
samplerStartBinding: number;
}
export const programLib: __private._cocos_render_scene_core_program_lib__ProgramLib;
export function getDeviceShaderVersion(device: gfx.Device): string;
export namespace scene {
/**
* @en The enumeration type for the fixed axis of the camera.
* The field of view along the corresponding axis would be fixed regardless of screen aspect changes.
* @zh 相机视角的锁定轴向枚举，在对应轴上不会跟随屏幕长宽比例变化。
*/
export enum CameraFOVAxis {
/**
* @en Vertically fixed camera
* @zh 在垂直轴向上锁定的相机
*/
VERTICAL = 0,
/**
* @en Horizontally fixed camera
* @zh 在水平轴向上锁定的相机
*/
HORIZONTAL = 1
}
/**
* @en The projection type enumeration of the camera.
* @zh 相机的投影类型枚举。
*/
export enum CameraProjection {
/**
* @en Orthogonal projection type
* @zh 正交投影类型
*/
ORTHO = 0,
/**
* @en Perspective projection type
* @zh 透视投影类型
*/
PERSPECTIVE = 1
}
/**
* @en The aperture enumeration of the camera, represent in f-number.
* The smaller the value is, the bigger the aperture is, and more light it can capture, but less depth it supports.
* @zh 相机的快门枚举，使用 f 值来表示。f 值越小，光圈就越大，进光量也越大，景深越浅。
*/
export enum CameraAperture {
/**
* f/1.8
*/
F1_8 = 0,
/**
* f/2.0
*/
F2_0 = 1,
/**
* f/2.2
*/
F2_2 = 2,
/**
* f/2.5
*/
F2_5 = 3,
/**
* f/2.8
*/
F2_8 = 4,
/**
* f/3.2
*/
F3_2 = 5,
/**
* f/3.5
*/
F3_5 = 6,
/**
* f/4.0
*/
F4_0 = 7,
/**
* f/4.5
*/
F4_5 = 8,
/**
* f/5.0
*/
F5_0 = 9,
/**
* f/5.6
*/
F5_6 = 10,
/**
* f/6.3
*/
F6_3 = 11,
/**
* f/7.1
*/
F7_1 = 12,
/**
* f/8
*/
F8_0 = 13,
/**
* f/9
*/
F9_0 = 14,
/**
* f/10
*/
F10_0 = 15,
/**
* f/11
*/
F11_0 = 16,
/**
* f/13
*/
F13_0 = 17,
/**
* f/14
*/
F14_0 = 18,
/**
* f/16
*/
F16_0 = 19,
/**
* f/18
*/
F18_0 = 20,
/**
* f/20
*/
F20_0 = 21,
/**
* f/22
*/
F22_0 = 22
}
/**
* @en The ISO enumeration of the camera, lower ISO means the camera is less sensitive to light.
* @zh 相机感光度枚举，越低的 ISO 数值表示相机对光更加不敏感。
*/
export enum CameraISO {
ISO100 = 0,
ISO200 = 1,
ISO400 = 2,
ISO800 = 3
}
/**
* @en Camera shutter enumeration, the value represents the speed of the shutter.
* @zh 相机快门枚举，枚举值表示快门速度。
*/
export enum CameraShutter {
/**
* 1 second
*/
D1 = 0,
/**
* 1/2 second
*/
D2 = 1,
/**
* 1/4 second
*/
D4 = 2,
/**
* 1/8 second
*/
D8 = 3,
/**
* 1/15 second
*/
D15 = 4,
/**
* 1/30 second
*/
D30 = 5,
/**
* 1/60 second
*/
D60 = 6,
/**
* 1/125 second
*/
D125 = 7,
/**
* 1/250 second
*/
D250 = 8,
/**
* 1/500 second
*/
D500 = 9,
/**
* 1/1000 second
*/
D1000 = 10,
/**
* 1/2000 second
*/
D2000 = 11,
/**
* 1/4000 second
*/
D4000 = 12
}
/**
* @en The type of the camera, mainly for marking different camera usage in XR, it determines the camera's viewport and parameters.
* @zh 相机类型，主要服务于标记 XR 中的不同相机用途，影响渲染的视口和对应的参数。
*/
export enum CameraType {
/**
* @en Default camera type
* @zh 默认相机类型
*/
DEFAULT = "Bad expression <-1>",
/**
* @en If a camera is set to be left eye, it will be used to render the left eye screen,
* otherwise, the left eye screen will be rendered using adjusted parameters based on XR main camera.
* @zh 如果设置了左眼相机，则在绘制左眼屏幕时使用，否则，就根据 XR 主相机的参数来计算左眼参数。
*/
LEFT_EYE = 0,
/**
* @en If a camera is set to be right eye, it will be used to render the right eye screen,
* otherwise, the right eye screen will be rendered using adjusted parameters based on XR main camera.
* @zh 如果设置了右眼相机，则在绘制右眼屏幕时使用，否则，就根据 XR 主相机的参数来计算左眼参数。
*/
RIGHT_EYE = 1,
/**
* @en The main camera, it could be used to calculate the parameters for both left eye and the right eye cameras.
* It could be converted from the default 3d camera.
* @zh XR 主相机，可以通过默认相机转换，也可以手动创建新的 XR 相机，可以计算出左右两个相机的相对参数。
*/
MAIN = 2
}
/**
* @en The spatial tracking signal type used by the camera in XR.
* @zh 相机使用的 XR 空间定位追踪信号类型。
*/
export enum TrackingType {
/**
* @en Camera without signal tracking in XR device.
* @zh 无追踪相机，不对 XR 设备的信号进行追踪。
*/
NO_TRACKING = 0,
/**
* @en Camera tracking position and rotation signals from XR device.
* @zh 相机追踪 XR 设备移动位置和旋转角度信号。
*/
POSITION_AND_ROTATION = 1,
/**
* @en Camera only tracking position signals from XR device.
* @zh 相机只追踪 XR 设备位置信号。
*/
POSITION = 2,
/**
* @en Camera only tracking rotation signals from XR device.
* @zh 相机只追踪 XR 设备旋转角度信号。
*/
ROTATION = 3
}
/**
* @en The usage of the camera, it's an engine internal marker enumeration.
* @zh 相机的用途枚举，这是引擎内部使用的标记枚举。
*/
export enum CameraUsage {
/**
* @en Camera used in editor
* @zh 编辑器下使用的相机
*/
EDITOR = 0,
/**
* @en Camera used in editor's game view.
* @zh 编辑器 GameView 视图下使用的相机。
*/
GAME_VIEW = 1,
/**
* @en Camera used in editor's scene view.
* @zh 编辑器场景编辑器视图下使用的相机。
*/
SCENE_VIEW = 2,
/**
* @en Camera used in editor's camera preview window.
* @zh 编辑器预览小窗视图下使用的相机。
*/
PREVIEW = 3,
/**
* @en Camera used in game, normally user created cameras are all GAME type.
* @zh 游戏视图下使用的相机，一般情况下用户创建的相机都是 GAME 类型。
*/
GAME = 100
}
/**
* @en The camera creation information struct
* @zh 用来创建相机的结构体
*/
export interface ICameraInfo {
/**
* @en The name of the camera.
* @zh 相机命名。
*/
name: string;
/**
* @en The node which the camera is attached to.
* @zh 相机挂载的节点。
*/
node: Node;
/**
* @en The projection type of the camera.
* @zh 相机的投影类型。
*/
projection: CameraProjection;
/**
* @en The id of the target display, if absent, it will be rendered on the default one.
* @zh 相机的目标屏幕，如果缺省，将会使用默认屏幕。
*/
targetDisplay?: number;
/**
* @en The target render window of the camera, is absent, the camera won't be rendered.
* @zh 相机的目标渲染窗口，如果缺省，该相机不会执行渲染流程。
*/
window?: __private._cocos_render_scene_core_render_window__RenderWindow | null;
/**
* @en Render priority of the camera. Cameras with higher depth are rendered after cameras with lower depth.
* @zh 相机的渲染优先级，值越小越优先渲染。
*/
priority: number;
/**
* @internal
*/
pipeline?: string;
/**
* @en The type of the camera, mainly for marking different camera usage in XR, it determines the camera's viewport and parameters.
* @zh 相机类型，主要服务于标记 XR 中的不同相机用途，影响渲染的视口和对应的参数。
*/
cameraType?: CameraType;
/**
* @en The spatial tracking signal type used by the camera in XR.
* @zh 相机使用的 XR 空间定位追踪信号类型。
*/
trackingType?: TrackingType;
/**
* @internal
*/
usage?: CameraUsage;
}
export const SKYBOX_FLAG: number;
/**
* @en The render camera representation in the render scene, it's managed by [[Camera]]
* @zh 渲染场景中的相机对象，由项目层的 [[Camera]] 管理。
*/
export class Camera {
/**
* @en This exposure value corresponding to default standard camera exposure parameters.
* @zh 默认相机的曝光值。
*/
static get standardExposureValue(): number;
/**
* @en The luminance unit scale used by area lights.
* @zh 默认局部光源使用的亮度单位缩放。
*/
static get standardLightMeterScale(): number;
/**
* @en The name of the camera
* @zh 相机的名称
*/
get name(): string | null;
/**
* @en The render scene to which the camera is attached
* @zh 相机所挂载的场景
*/
get scene(): RenderScene | null;
/**
* @en The node of the camera which determines its transform in world space.
* @zh 相机绑定的节点，决定了它在世界空间的变换矩阵
*/
set node(val: Node);
get node(): Node;
/**
* @en The unique ID of system window which the camera will render to.
* @zh 相机关联的渲染窗口ID
*/
get systemWindowId(): number;
/**
* @en The render window of the camera
* @zh 相机关联的渲染窗口
*/
set window(val: __private._cocos_render_scene_core_render_window__RenderWindow);
get window(): __private._cocos_render_scene_core_render_window__RenderWindow;
/**
* @en Whether the camera is enabled, a disabled camera won't be processed in the render pipeline.
* @zh 相机是否启用，未启用的相机不会被渲染
*/
set enabled(val: boolean);
get enabled(): boolean;
/**
* @en Visibility mask of the camera, declaring a set of node layers that will be visible to this camera.
* @zh 相机的可见性掩码，声明在当前相机中可见的节点层级集合。
*/
set visibility(vis: number);
get visibility(): number;
/**
* @en Render priority of the camera. Cameras with higher depth are rendered after cameras with lower depth.
* @zh 相机的渲染优先级，值越小越优先渲染。
*/
get priority(): number;
set priority(val: number);
/**
* @en The width of the camera's view size
* @zh 相机的视图宽度
*/
get width(): number;
/**
* @en The height of the camera's view size
* @zh 相机的视图高度
*/
get height(): number;
/**
* @en The world position of the camera
* @zh 相机的世界坐标
*/
set position(val: math.Vec3);
get position(): math.Vec3;
/**
* @en The forward vector of the camera's look direction
* @zh 指向相机观察方向的向量
*/
set forward(val: math.Vec3);
get forward(): math.Vec3;
/**
* @en Camera aperture, controls the exposure parameter.
* @zh 相机光圈，影响相机的曝光参数。
*/
set aperture(val: CameraAperture);
get aperture(): CameraAperture;
/**
* @en Camera aperture value.
* @zh 相机光圈值。
*/
get apertureValue(): number;
/**
* @en Camera shutter, controls the exposure parameter.
* @zh 相机快门，影响相机的曝光参数。
*/
set shutter(val: CameraShutter);
get shutter(): CameraShutter;
/**
* @en Camera shutter value.
* @zh 相机快门值。
*/
get shutterValue(): number;
/**
* @en Camera ISO, controls the exposure parameter.
* @zh 相机感光度，影响相机的曝光参数。
*/
set iso(val: CameraISO);
get iso(): CameraISO;
/**
* @en Camera ISO value.
* @zh 相机感光度值。
*/
get isoValue(): number;
/**
* @en The calculated exposure of the camera
* @zh 相机的曝光参数
*/
get exposure(): number;
/**
* @en Clearing flags of the camera, specifies which part of the framebuffer will be actually cleared every frame.
* @zh 相机的缓冲清除标志位，指定帧缓冲的哪部分要每帧清除。
*/
get clearFlag(): gfx.ClearFlags;
set clearFlag(flag: gfx.ClearFlags);
/**
* @en Clearing color of the camera.
* @zh 相机的颜色缓冲默认值。
*/
set clearColor(val: math.IVec4Like);
get clearColor(): math.IVec4Like;
/**
* @en Clearing depth of the camera.
* @zh 相机的深度缓冲默认值。
*/
get clearDepth(): number;
set clearDepth(depth: number);
/**
* @en Clearing stencil of the camera.
* @zh 相机的模板缓冲默认值。
*/
get clearStencil(): number;
set clearStencil(stencil: number);
/**
* @en The projection type of the camera.
* @zh 相机的投影类型。
*/
set projectionType(val: CameraProjection);
get projectionType(): CameraProjection;
/**
* @en The aspect ratio of the camera
* @zh 相机视图的长宽比
*/
get aspect(): number;
/**
* @en The viewport height of the orthogonal type camera.
* @zh 正交相机的视角高度。
*/
set orthoHeight(val: number);
get orthoHeight(): number;
/**
* @en The axis on which the FOV would be fixed regardless of screen aspect changes.
* @zh 指定视角的固定轴向，在此轴上不会跟随屏幕长宽比例变化。
*/
set fovAxis(axis: CameraFOVAxis);
get fovAxis(): CameraFOVAxis;
/**
* @en Field of view of the camera.
* @zh 相机的视角大小。
*/
set fov(fov: number);
get fov(): number;
/**
* @en Near clipping distance of the camera, should be as large as possible within acceptable range.
* @zh 相机的近裁剪距离，应在可接受范围内尽量取最大。
*/
set nearClip(nearClip: number);
get nearClip(): number;
/**
* @en Far clipping distance of the camera, should be as small as possible within acceptable range.
* @zh 相机的远裁剪距离，应在可接受范围内尽量取最小。
*/
set farClip(farClip: number);
get farClip(): number;
/**
* @en The viewport rect of the camera, pre-rotated (i.e. always in identity/portrait mode) if possible.
* @zh 相机的视口矩形，如果设备允许的话，这个视口会永远保持竖屏状态，由渲染流程保障旋转的正确。
*/
get viewport(): math.Rect;
set viewport(val: math.Rect);
/**
* @en The view frustum of the camera
* @zh 相机的视锥体
*/
set frustum(val: geometry.Frustum);
get frustum(): geometry.Frustum;
/**
* @en The view matrix of the camera
* @zh 相机的视图矩阵
*/
get matView(): math.Mat4;
/**
* @en The projection matrix of the camera
* @zh 相机的投影矩阵
*/
get matProj(): math.Mat4;
/**
* @en The inverse of the projection matrix of the camera
* @zh 相机的逆投影矩阵
*/
get matProjInv(): math.Mat4;
/**
* @en The view projection matrix of the camera
* @zh 相机的视图投影矩阵
*/
get matViewProj(): math.Mat4;
/**
* @en The inverse of the view projection matrix of the camera
* @zh 相机的逆视图投影矩阵
*/
get matViewProjInv(): math.Mat4;
/**
* @en Whether the camera is fixed size or matching the window size.
* @zh 相机是固定尺寸还是跟随屏幕尺寸
*/
isWindowSize: boolean;
/**
* @en Scale of the internal buffer size,
* set to 1 to keep the same with the canvas size.
* @zh 相机内部缓冲尺寸的缩放值, 1 为与 canvas 尺寸相同。
*/
screenScale: number;
postProcess: postProcess.PostProcess | null;
usePostProcess: boolean;
pipeline: string;
constructor(device: gfx.Device);
/**
* @en Initialize the camera, normally you shouldn't invoke this function, it's managed automatically.
* @zh 初始化相机，开发者通常不应该使用这个方法，初始化流程是自动管理的。
*/
initialize(info: ICameraInfo): void;
/**
* @en Destroy the camera, you shouldn't invoke this function, it's managed by the render scene.
* @zh 销毁相机，开发者不应该使用这个方法，销毁流程是由 RenderScene 管理的。
*/
destroy(): void;
/**
* @en Attach the camera to the given render scene so that it will be rendered in it.
* @zh 将相机添加到相关的渲染场景中，以便可以被渲染器渲染。
* @param scene @en The render scene @zh 渲染场景
*/
attachToScene(scene: RenderScene): void;
/**
* @en Detach the camera from previously attached render scene. It will no longer be rendered.
* @zh 将相机从之前设置的渲染场景移除，之后将不会再被渲染。
*/
detachFromScene(): void;
/**
* @en Resize the view size of the camera.
* @zh 重置相机视图尺寸
* @param width The width of the view size
* @param height The height of the view size
*/
resize(width: number, height: number): void;
/**
* @en Set a fixed size for the camera view.
* @zh 设置固定相机视图尺寸
* @param width The width of the view size
* @param height The height of the view size
*/
setFixedSize(width: number, height: number): void;
/**
* Editor specific gizmo camera logic
* @internal
*/
syncCameraEditor(camera: any): void;
/**
* @en Update the camera's builtin matrixes
* @zh 更新相机的视图、投影等矩阵
* @param forceUpdate If force update, then dirty flag will be ignored
*/
update(forceUpdate?: boolean): void;
get surfaceTransform(): gfx.SurfaceTransform;
/**
* @en Set the viewport in oriented space (equal to the actual screen rotation)
* @zh 在目标朝向空间（实际屏幕朝向）内设置相机视口
*/
setViewportInOrientedSpace(val: math.Rect): void;
/**
* @en create geometry renderer for this camera
* @zh 创建这个摄像机的几何体渲染器
*/
initGeometryRenderer(): void;
/**
* @en get geometry renderer of this camera
* @zh 获取这个摄像机的几何体渲染器
* @returns @en return the geometry renderer @zh 返回几何体渲染器
*/
get geometryRenderer(): GeometryRenderer | null;
get cameraType(): CameraType;
set cameraType(type: CameraType);
get trackingType(): TrackingType;
set trackingType(type: TrackingType);
get cameraUsage(): CameraUsage;
set cameraUsage(usage: CameraUsage);
/**
* @en Change the target render window to another one
* @zh 修改相机的目标渲染窗口
* @param window The target render window, could be null
*/
changeTargetWindow(window?: __private._cocos_render_scene_core_render_window__RenderWindow | null): void;
/**
* @en Detach camera from the render window
* @zh 将 camera 从渲染窗口移除
*/
detachCamera(): void;
/**
* @en Transform a screen position (in oriented space) to a world space ray
* @zh 将一个屏幕空间（在实际朝向下）点转换到世界空间的射线
* @param out the resulting ray
* @param x the screen x of the position
* @param y the screen y of the position
* @returns the resulting ray
*/
screenPointToRay(out: geometry.Ray, x: number, y: number): geometry.Ray;
/**
* @en Transform a screen position (in oriented space) to world space
* @zh 将一个屏幕空间（在实际朝向下）位置转换到世界空间
* @param out the resulting vector
* @param screenPos the screen position to be transformed
* @returns the resulting vector
*/
screenToWorld(out: math.Vec3, screenPos: math.Vec3): math.Vec3;
/**
* @en Transform a world space position to screen space rendered by the camera
* @zh 将一个世界空间位置转换到相机渲染后的屏幕空间
* @param out the resulting vector
* @param worldPos the world position to be transformed
* @returns the resulting vector
*/
worldToScreen(out: math.Vec3, worldPos: math.Vec3 | Readonly): math.Vec3;
/**
* @en Transform a world space matrix to screen space rendered by the camera
* @zh 将一个世界空间矩阵转换到相机渲染后的屏幕空间
* @param out the resulting matrix
* @param worldMatrix the world space matrix to be transformed
* @param width framebuffer width
* @param height framebuffer height
* @returns the resulting matrix
*/
worldMatrixToScreen(out: math.Mat4, worldMatrix: math.Mat4, width: number, height: number): math.Mat4;
/**
* @en Calculate and set oblique view frustum projection matrix.
* @zh 计算并设置斜视锥体投影矩阵
* @param clipPlane clip plane in camera space
*/
calculateObliqueMat(viewSpacePlane: math.Vec4): void;
getClipSpaceMinz(): number;
/**
* @en Set exposure with actual value.
* @zh 设置相机的曝光值
* @param ev100
*/
protected setExposure(ev100: any): void;
}
export enum ModelType {
DEFAULT = 0,
SKINNING = 1,
BAKED_SKINNING = 2,
BATCH_2D = 3,
PARTICLE_BATCH = 4,
LINE = 5
}
/**
* @en A representation of a model instance
* The base model class, which is the core component of [[MeshRenderer]],
* adds its own Model to the rendered scene for rendering submissions when [[MeshRenderer]] is enabled.
* This type of object represents a rendering instance in a scene, and it can contain multiple sub models,
* each of which corresponds to a material. These sub models share the same location and form a complete object.
* Each sub model references a sub mesh resource, which provides vertex and index buffers for rendering.
* @zh 代表一个模型实例
* 基础模型类，它是 [[MeshRenderer]] 的核心组成部分，在 [[MeshRenderer]] 启用时会将自己的 Model 添加到渲染场景中用于提交渲染。
* 此类型对象代表一个场景中的渲染实例，它可以包含多个子模型，每个子模型对应一个材质。这些子模型共享同样的位置，组成一个完整的物体。
* 每个子模型引用一个子网格资源，后者提供渲染所用的顶点与索引缓冲。
*/
export class Model {
/**
* @en Sub models of the current model
* @zh 获取所有子模型
*/
get subModels(): SubModel[];
/**
* @en Whether the model is initialized
* @zh 是否初始化
*/
get inited(): boolean;
/**
* @en The axis-aligned bounding box of the model in the world space
* @zh 获取世界空间包围盒
*/
get worldBounds(): geometry.AABB | null;
/**
* @en The axis-aligned bounding box of the model in the model space
* @zh 获取模型空间包围盒
*/
get modelBounds(): geometry.AABB | null;
/**
* @en The ubo buffer of the model
* @zh 获取模型的 ubo 缓冲
*/
get localBuffer(): gfx.Buffer | null;
/**
* @en The SH ubo buffer of the model
* @zh 获取模型的球谐 ubo 缓冲
*/
get localSHBuffer(): gfx.Buffer | null;
/**
* @en The world bound ubo buffer
* @zh 获取世界包围盒 ubo 缓冲
*/
get worldBoundBuffer(): gfx.Buffer | null;
/**
* @en The time stamp of last update
* @zh 获取上次更新时间戳
*/
get updateStamp(): number;
/**
* @en Use LightProbe or not
* @zh 光照探针开关
*/
get useLightProbe(): boolean;
set useLightProbe(val: boolean);
/**
* @en located tetrahedron index
* @zh 模型所处的四面体索引
*/
get tetrahedronIndex(): number;
set tetrahedronIndex(index: number);
/**
* @en Model level shadow bias
* @zh 阴影偏移值
*/
get shadowBias(): number;
set shadowBias(val: number);
/**
* @en Model level shadow normal bias
* @zh 阴影法线偏移值
*/
get shadowNormalBias(): number;
set shadowNormalBias(val: number);
/**
* @en Whether the model should receive shadow
* @zh 是否接收阴影
*/
get receiveShadow(): boolean;
set receiveShadow(val: boolean);
/**
* @en Whether the model should cast shadow
* @zh 是否投射阴影
*/
get castShadow(): boolean;
set castShadow(val: boolean);
/**
* @en Gets or sets receive direction Light.
* @zh 获取或者设置接收平行光光照。
*/
get receiveDirLight(): boolean;
set receiveDirLight(val: boolean);
/**
* @en The node to which the model belongs
* @zh 模型所在的节点
*/
get node(): Node;
set node(n: Node);
/**
* @en Model's transform
* @zh 模型的变换
*/
get transform(): Node;
set transform(n: Node);
/**
* @en Model's visibility tag
* Model's visibility flags, it's different from [[Node.layer]],
* but it will also be compared with [[Camera.visibility]] during culling process.
* @zh 模型的可见性标志
* 模型的可见性标志与 [[Node.layer]] 不同，它会在剔除阶段与 [[Camera.visibility]] 进行比较
*/
get visFlags(): number;
set visFlags(val: number);
/**
* @en Whether the model is enabled in the render scene so that it will be rendered
* @zh 模型是否在渲染场景中启用并被渲染
*/
get enabled(): boolean;
set enabled(val: boolean);
/**
* @en Rendering priority in the transparent queue of model.
* @zh Model 在透明队列中的渲染排序优先级
*/
get priority(): number;
set priority(val: number);
/**
* @en Whether the model can be render by the reflection probe
* @zh 模型是否能被反射探针渲染
*/
get bakeToReflectionProbe(): boolean;
set bakeToReflectionProbe(val: boolean);
/**
* @en Reflection probe type
* @zh 反射探针类型。
*/
get reflectionProbeType(): ReflectionProbeType;
set reflectionProbeType(val: ReflectionProbeType);
/**
* @en sets or gets reflection probe id
* @zh 设置或获取反射探针id。
*/
get reflectionProbeId(): number;
set reflectionProbeId(val: number);
/**
* @en Sets or gets the reflection probe id for blend.
* @zh 设置或获取用于混合的反射探针id。
*/
get reflectionProbeBlendId(): number;
set reflectionProbeBlendId(val: number);
/**
* @en Sets or gets the reflection probe blend weight.
* @zh 设置或获取反射探针混合权重。
*/
get reflectionProbeBlendWeight(): number;
set reflectionProbeBlendWeight(val: number);
/**
* @en The type of the model
* @zh 模型类型
*/
type: ModelType;
/**
* @en The render scene to which the model belongs
* @zh 模型所在的场景
*/
scene: RenderScene | null;
/**
* @en Whether dynamic batching is enabled for model
* @zh 是否动态合批
*/
isDynamicBatching: boolean;
/**
* @en The world axis-aligned bounding box
* @zh 世界空间包围盒
*/
protected _worldBounds: geometry.AABB | null;
/**
* @en The model axis-aligned bounding box
* @zh 模型空间包围盒
*/
protected _modelBounds: geometry.AABB | null;
/**
* @en Sub models
* @zh 子模型
*/
protected _subModels: SubModel[];
/**
* @en The node to which the model belongs
* @zh 模型所在的节点
*/
protected _node: Node;
/**
* @en Model's transform
* @zh 子模型的变换
*/
protected _transform: Node;
/**
* @en Current gfx device
* @zh 当前 GFX 设备
*/
protected _device: gfx.Device;
/**
* @en Whether the model is initialized
* @zh 是否初始化过
*/
protected _inited: boolean;
/**
* @en Descriptor set count
* @zh 描述符集合个数
*/
protected _descriptorSetCount: number;
/**
* @en Time stamp for last update
* @zh 更新时间戳
*/
protected _updateStamp: number;
/**
* @en Local ubo data dirty flag
* @zh 本地 ubo 数据是否修改过
*/
protected _localDataUpdated: boolean;
/**
* @en Local ubo data
* @zh 本地 ubo 数据
*/
protected _localData: Float32Array;
/**
* @en Local ubo buffer
* @zh 本地 ubo 缓冲
*/
protected _localBuffer: gfx.Buffer | null;
/**
* @en Local SH ubo data
* @zh 本地球谐 ubo 数据
*/
protected _localSHData: Float32Array | null;
/**
* @en Local SH ubo buffer
* @zh 本地球谐 ubo 缓冲
*/
protected _localSHBuffer: gfx.Buffer | null;
/**
* @en World AABB buffer
* @zh 世界空间包围盒缓冲
*/
protected _worldBoundBuffer: gfx.Buffer | null;
/**
* @en Whether the model should receive shadow
* @zh 是否接收阴影
*/
protected _receiveShadow: boolean;
/**
* @en Whether the model should cast shadow
* @zh 是否投射阴影
*/
protected _castShadow: boolean;
/**
* @en Is received direction Light.
* @zh 是否接收平行光光照。
*/
protected _receiveDirLight: boolean;
/**
* @en Shadow bias
* @zh 阴影偏移
*/
protected _shadowBias: number;
/**
* @en Shadow normal bias
* @zh 阴影法线偏移
*/
protected _shadowNormalBias: number;
/**
* @en Reflect probe Id
* @zh 使用第几个反射探针
*/
protected _reflectionProbeId: number;
/**
* @en Use which probe to blend
* @zh 使用第几个反射探针进行混合
*/
protected _reflectionProbeBlendId: number;
/**
* @en Reflection probe blend weight
* @zh 反射探针混合权重
*/
protected _reflectionProbeBlendWeight: number;
/**
* @en Whether the model is enabled in the render scene so that it will be rendered
* @zh 模型是否在渲染场景中启用并被渲染
*/
protected _enabled: boolean;
/**
* @en The visibility flags
* @zh 可见性标志位
*/
protected _visFlags: number;
protected _priority: number;
/**
* @en Whether the model can be render by the reflection probe
* @zh 模型是否能被反射探针渲染
*/
protected _bakeToReflectionProbe: boolean;
/**
* @en Reflection probe type.
* @zh 反射探针类型。
*/
protected _reflectionProbeType: ReflectionProbeType;
/**
* @internal
* @en native object
* @zh 原生对象
*/
/**
* @internal
* @en return native object
* @zh 返回原生对象
*/
/**
* @en Constructor to create an empty model
* @zh 创建一个空模型
*/
constructor();
/**
* @en Initialize the model
* @zh 初始化模型
*/
initialize(): void;
/**
* @en Destroy the model
* @zh 销毁模型
*/
destroy(): void;
/**
* @en Attach the model to a [[renderer.RenderScene]]
* @zh 添加模型到渲染场景 [[renderer.RenderScene]] 中
* @param scene destination scene
*/
attachToScene(scene: RenderScene): void;
/**
* @en Detach the model from its render scene
* @zh 移除场景中的模型
*/
detachFromScene(): void;
/**
* @en Update the model's transform
* @zh 更新模型的变换
* @param stamp time stamp
*/
updateTransform(stamp: number): void;
/**
* @en Update the model's world AABB
* @zh 更新模型的世界空间包围盒
*/
updateWorldBound(): void;
/**
* @en Update the model's ubo
* @zh 更新模型的 ubo
* @param stamp time stamp
*/
updateUBOs(stamp: number): void;
showTetrahedron(): boolean;
/**
* @en Clear the model's SH ubo
* @zh 清除模型的球谐 ubo
*/
clearSHUBOs(): void;
/**
* @en Update the model's SH ubo
* @zh 更新模型的球谐 ubo
*/
updateSHUBOs(): void;
/**
* @en Create the model's AABB
* @zh 创建模型的包围盒
* @param minPos min position of the AABB
* @param maxPos max position of the AABB
*/
createBoundingShape(minPos?: math.Vec3, maxPos?: math.Vec3): void;
/**
* @en Initialize a sub model with the sub mesh data and the material.
* @zh 用子网格数据和材质初始化一个子模型。
* @param idx sub model's index
* @param subMeshData sub mesh
* @param mat sub material
*/
initSubModel(idx: number, subMeshData: RenderingSubMesh, mat: Material): void;
/**
* @en Set material for a given sub model
* @zh 为指定的子模型设置材质
* @param idx sub model's index
* @param subMesh sub mesh
*/
setSubModelMesh(idx: number, subMesh: RenderingSubMesh): void;
/**
* @en Set a sub material
* @zh 设置一个子材质
* @param idx sub model's index
* @param mat sub material
*/
setSubModelMaterial(idx: number, mat: Material): void;
/**
* @en Pipeline changed callback
* @zh 管线更新回调
*/
onGlobalPipelineStateChanged(): void;
/**
* @en Shader macro changed callback
* @zh Shader 宏更新回调
*/
onMacroPatchesStateChanged(): void;
onGeometryChanged(): void;
/**
* @internal
* If the model has lighting map
* initialize lighting map info before model initializing
* because the lighting map will influence the shader
*/
initLightingmap(texture: Texture2D | null, uvParam: math.Vec4): void;
/**
* @en Update the light map info
* @zh 更新光照贴图信息
* @param texture light map
* @param uvParam uv coordinate
*/
updateLightingmap(texture: Texture2D | null, uvParam: math.Vec4): void;
/**
* @en Update the cube map of the reflection probe
* @zh 更新反射探针的立方体贴图
* @param texture probe cubemap
*/
updateReflectionProbeCubemap(texture: TextureCube | null): void;
/**
* @en Update the cube map of the reflection probe for blend
* @zh 更新用于blend的反射探针立方体贴图
* @param texture probe cubemap
*/
updateReflectionProbeBlendCubemap(texture: TextureCube | null): void;
/**
* @en Update the planar relflection map of the reflection probe
* @zh 更新反射探针的平面反射贴图
* @param texture planar relflection map
*/
updateReflectionProbePlanarMap(texture: gfx.Texture | null): void;
/**
* @en Update the data map of the reflection probe
* @zh 更新反射探针的数据贴图
* @param texture data map
*/
updateReflectionProbeDataMap(texture: Texture2D | null): void;
/**
* @en Update the shadow bias
* @zh 更新阴影偏移
*/
updateLocalShadowBias(): void;
/**
* @en Update the id of reflection probe
* @zh 更新物体使用哪个反射探针
*/
updateReflectionProbeId(): void;
/**
* @en Return shader's macro patches
* @zh 获取 shader 宏
* @param subModelIndex sub model's index
*/
getMacroPatches(subModelIndex: number): IMacroPatch[] | null;
protected _updateAttributesAndBinding(subModelIndex: number): void;
protected _updateInstancedAttributes(attributes: gfx.Attribute[], subModel: SubModel): void;
protected _initLocalDescriptors(subModelIndex: number): void;
protected _initLocalSHDescriptors(subModelIndex: number): void;
protected _initWorldBoundDescriptors(subModelIndex: number): void;
protected _updateLocalDescriptors(subModelIndex: number, descriptorSet: gfx.DescriptorSet): void;
protected _updateLocalSHDescriptors(subModelIndex: number, descriptorSet: gfx.DescriptorSet): void;
protected _updateWorldBoundDescriptors(subModelIndex: number, descriptorSet: gfx.DescriptorSet): void;
}
export interface IInstancedAttributeBlock {
buffer: Uint8Array;
views: __private.__types_globals__TypedArray[];
attributes: gfx.Attribute[];
}
/**
* @en A sub part of the model, it describes how to render a specific sub mesh.
* It contains geometry information in [[RenderingSubMesh]] and all sort of rendering configuration like shaders, macro patches, passes etc.
* @zh 组成模型对象的子模型，它用来描述如何渲染模型的一个子网格。
* 它包含 [[RenderingSubMesh]] 代表的几何网格信息和所有渲染需要的数据，比如着色器程序，着色器宏定义，渲染 pass，等。
*/
export class SubModel {
protected _device: gfx.Device | null;
protected _passes: Pass[] | null;
protected _shaders: gfx.Shader[] | null;
protected _subMesh: RenderingSubMesh | null;
protected _patches: IMacroPatch[] | null;
protected _priority: pipeline.RenderPriority;
protected _inputAssembler: gfx.InputAssembler | null;
protected _descriptorSet: gfx.DescriptorSet | null;
protected _worldBoundDescriptorSet: gfx.DescriptorSet | null;
protected _reflectionTex: gfx.Texture | null;
protected _reflectionSampler: gfx.Sampler | null;
protected _instancedAttributeBlock: IInstancedAttributeBlock;
protected _instancedWorldMatrixIndex: number;
protected _instancedSHIndex: number;
protected _useReflectionProbeType: number;
/**
* @en
* sub model's passes
* @zh
* 子模型的 passes
* @param passes @en The passes @zh 设置的 passes
*/
/**
* @en Render passes for the sub-model
* @zh 子模型的渲染 pass
*/
set passes(passes: Pass[]);
get passes(): Pass[];
/**
* @en Shaders for the sub-model, each shader corresponds to one of the [[passes]]
* @zh 子模型的着色器程序列表，每个着色器程序对应其中一个渲染 [[passes]]
*/
get shaders(): gfx.Shader[];
/**
* @en The rendering sub mesh for the sub-model, each sub-model can only have one sub mesh.
* @zh 用于渲染的子网格对象，每个子模型只能包含一个子网格。
*/
set subMesh(subMesh: RenderingSubMesh);
get subMesh(): RenderingSubMesh;
/**
* @en The rendering priority of the sub-model
* @zh 子模型的渲染优先级
*/
set priority(val: pipeline.RenderPriority);
get priority(): pipeline.RenderPriority;
/**
* @en The low level input assembler which contains geometry data
* @zh 底层渲染用的输入汇集器，包含几何信息
*/
get inputAssembler(): gfx.InputAssembler;
/**
* @en The descriptor set used for sub-model rendering
* @zh 底层渲染子模型用的描述符集组
*/
get descriptorSet(): gfx.DescriptorSet;
/**
* @en The descriptor set for world bound
* @zh 用于存储世界包围盒的描述符集组
*/
get worldBoundDescriptorSet(): gfx.DescriptorSet | null;
/**
* @en The macro patches for the shaders
* @zh 着色器程序所用的宏定义组合
*/
get patches(): Readonly;
/**
* @en The instance attribute block, access by sub model
* @zh 硬件实例化属性，通过子模型访问
*/
get instancedAttributeBlock(): IInstancedAttributeBlock;
/**
* @en Get or set instance matrix id, access by sub model
* @zh 获取或者设置硬件实例化中的矩阵索引，通过子模型访问
*/
set instancedWorldMatrixIndex(val: number);
get instancedWorldMatrixIndex(): number;
/**
* @en Get or set instance SH id, access by sub model
* @zh 获取或者设置硬件实例化中的球谐索引，通过子模型访问
*/
set instancedSHIndex(val: number);
get instancedSHIndex(): number;
/**
* @en Gets or sets the type of reflection probe, Used to process instance
* @zh 获取或设置使用反射探针的类型，用于处理instance
*/
set useReflectionProbeType(val: number);
get useReflectionProbeType(): number;
/**
* @en
* init sub model
* @zh
* 子模型初始化
* @param subMesh @en The sub mesh @zh 子网格资源
* @param passes @en The passes @zh 渲染的 passes
* @param patches @en The shader's macro @zh 着色器的宏定义
*/
initialize(subMesh: RenderingSubMesh, passes: Pass[], patches?: IMacroPatch[] | null): void;
/**
* @en
* destroy sub model
* @zh
* 销毁子模型
*/
destroy(): void;
/**
* @en
* update sub model
* @zh
* 更新子模型
*/
update(): void;
/**
* @en Pipeline changed callback
* @zh 管线更新回调
*/
onPipelineStateChanged(): void;
/**
* @en Shader macro changed callback
* @zh Shader 宏更新回调
*/
onMacroPatchesStateChanged(patches: IMacroPatch[] | null): void;
/**
* @en
* geometry changed callback
* @zh
* 几何数据改变后的回调
*/
onGeometryChanged(): void;
/**
* @en
* get instanced attribute index
* @zh
* 获取硬件实例化相关索引
*/
/**
* @internal
*/
getInstancedAttributeIndex(name: string): number;
/**
* @en
* update instancing related data, invoked by model
* @zh
* 更新硬件实例化相关数据，一般由model调用
*/
/**
* @internal
*/
updateInstancedWorldMatrix(mat: math.Mat4, idx: number): void;
/**
* @en
* update instancing SH data, invoked by model
* @zh
* 更新硬件实例化球谐数据，一般由model调用
*/
/**
* @internal
*/
updateInstancedSH(data: Float32Array, idx: number): void;
/**
* @en
* update instancing related data, invoked by model
* @zh
* 更新硬件实例化相关数据，一般由model调用
*/
/**
* @internal
*/
UpdateInstancedAttributes(attributes: gfx.Attribute[]): void;
protected _flushPassInfo(): void;
}
/**
* @en Ambient lighting representation in the render scene.
* The initial data is setup in [[SceneGlobals.ambient]].
* @zh 渲染场景中的环境光照设置。
* 初始值是由 [[SceneGlobals.ambient]] 设置的。
*/
export class Ambient {
/**
* @en Default sun illuminance
* @zh 默认太阳亮度
*/
static SUN_ILLUM: number;
/**
* @en Default sky illuminance
* @zh 默认天空亮度
*/
static SKY_ILLUM: number;
/**
* @en Enable ambient
* @zh 是否开启环境光
*/
set enabled(val: boolean);
get enabled(): boolean;
/**
* @en Sky color
* @zh 天空颜色
*/
get skyColor(): math.Vec4;
set skyColor(color: math.Vec4);
/**
* @en Sky illuminance
* @zh 天空亮度
*/
get skyIllum(): number;
set skyIllum(illum: number);
/**
* @en Ground color
* @zh 地面颜色
*/
get groundAlbedo(): math.Vec4;
set groundAlbedo(color: math.Vec4);
protected _groundAlbedoHDR: math.Vec4;
protected _skyColorHDR: math.Vec4;
protected _skyIllumHDR: number;
protected _groundAlbedoLDR: math.Vec4;
protected _skyColorLDR: math.Vec4;
protected _skyIllumLDR: number;
protected _mipmapCount: number;
protected _enabled: boolean;
initialize(ambientInfo: AmbientInfo): void;
}
export const EnvironmentLightingType: {
/**
* @zh
* 半球漫反射
* @en
* hemisphere diffuse
* @readonly
*/
HEMISPHERE_DIFFUSE: number;
/**
* @zh
* 半球漫反射和环境反射
* @en
* hemisphere diffuse and Environment reflection
* @readonly
*/
AUTOGEN_HEMISPHERE_DIFFUSE_WITH_REFLECTION: number;
/**
* @zh
* 漫反射卷积图和环境反射
* @en
* diffuse convolution map and environment reflection
* @readonly
*/
DIFFUSEMAP_WITH_REFLECTION: number;
};
/**
* @en The skybox configuration of the render scene,
* currently some rendering options like hdr and ibl lighting configuration is also here.
* @zh 渲染场景的天空盒配置，目前一些渲染配置，比如 HDR 模式和环境光照配置也在 Skybox 中。
*/
export class Skybox {
/**
* @en The Model object of the skybox
* @zh 天空盒的 Model 对象
*/
get model(): Model | null;
/**
* @en Whether activate skybox in the scene
* @zh 是否启用天空盒？
*/
get enabled(): boolean;
set enabled(val: boolean);
/**
* @en Whether HDR mode is enabled
* @zh 是否启用HDR？
*/
get useHDR(): boolean;
set useHDR(val: boolean);
/**
* @en Whether use image based lighting for PBR materials
* @zh 是否启用IBL？
*/
get useIBL(): boolean;
set useIBL(val: boolean);
/**
* @en Whether use diffuse convolution map lighting
* @zh 是否为IBL启用漫反射卷积图？
*/
get useDiffuseMap(): boolean;
set useDiffuseMap(val: boolean);
/**
* @en Whether enable RGBE data support in skybox shader
* @zh 是否需要开启 shader 内的 RGBE 数据支持？
*/
get isRGBE(): boolean;
/**
* @en Whether to use offline baked convolutional maps
* @zh 是否使用离线烘焙的卷积图？
*/
get useConvolutionMap(): boolean;
/**
* @en The texture cube used for the skybox
* @zh 使用的立方体贴图
*/
get envmap(): TextureCube | null;
set envmap(val: TextureCube | null);
/**
* @en The texture cube used diffuse convolution map
* @zh 使用的漫反射卷积图
*/
get diffuseMap(): TextureCube | null;
set diffuseMap(val: TextureCube | null);
get reflectionMap(): TextureCube | null;
get editableMaterial(): MaterialInstance | null;
protected _envmapLDR: TextureCube | null;
protected _envmapHDR: TextureCube | null;
protected _diffuseMapLDR: TextureCube | null;
protected _diffuseMapHDR: TextureCube | null;
protected _globalDSManager: __private._cocos_rendering_global_descriptor_set_manager__GlobalDSManager | null;
protected _model: Model | null;
protected _default: TextureCube | null;
protected _enabled: boolean;
protected _useIBL: boolean;
protected _useHDR: boolean;
protected _useDiffuseMap: boolean;
protected _editableMaterial: MaterialInstance | null;
protected _activated: boolean;
protected _reflectionHDR: TextureCube | null;
protected _reflectionLDR: TextureCube | null;
protected _rotationAngle: number;
initialize(skyboxInfo: SkyboxInfo): void;
/**
* @en Set the environment maps for HDR and LDR mode
* @zh 为 HDR 和 LDR 模式设置环境贴图
* @param envmapHDR @en Environment map for HDR mode @zh HDR 模式下的环境贴图
* @param envmapLDR @en Environment map for LDR mode @zh LDR 模式下的环境贴图
*/
setEnvMaps(envmapHDR: TextureCube | null, envmapLDR: TextureCube | null): void;
/**
* @en Set the diffuse maps
* @zh 设置环境光漫反射贴图
* @param diffuseMapHDR @en Diffuse map for HDR mode @zh HDR 模式下的漫反射贴图
* @param diffuseMapLDR @en Diffuse map for LDR mode @zh LDR 模式下的漫反射贴图
*/
setDiffuseMaps(diffuseMapHDR: TextureCube | null, diffuseMapLDR: TextureCube | null): void;
/**
* @en Set custom skybox material
* @zh 设置自定义的天空盒材质
* @param skyboxMat @en Skybox material @zh 天空盒材质
*/
setSkyboxMaterial(skyboxMat: Material | null): void;
/**
* @en Set the environment reflection convolution map
* @zh 设置环境反射卷积图
* @param reflectionHDR @en Reflection convolution map for HDR mode @zh HDR 模式下的反射卷积图
* @param reflectionLDR @en Reflection convolution map for LDR mode @zh LDR 模式下的反射卷积图
*/
setReflectionMaps(reflectionHDR: TextureCube | null, reflectionLDR: TextureCube | null): void;
/**
* @en Set skybox rotation angle
* @zh 设置天空盒旋转角度
* @param angle @en rotation angle @zh 旋转角度
*/
setRotationAngle(angle: number): void;
getRotationAngle(): number;
updateMaterialRenderInfo(): void;
activate(): void;
protected _updatePipeline(): void;
protected _updateGlobalBinding(): void;
protected _updateSubModes(): void;
}
/**
* @zh 阴影贴图分辨率。
* @en The shadow map size.
* @static
* @enum Shadows.ShadowSize
*/
export const ShadowSize: {
/**
* @zh 分辨率 256 * 256。
* @en shadow resolution 256 * 256.
* @readonly
*/
Low_256x256: number;
/**
* @zh 分辨率 512 * 512。
* @en shadow resolution 512 * 512.
* @readonly
*/
Medium_512x512: number;
/**
* @zh 分辨率 1024 * 1024。
* @en shadow resolution 1024 * 1024.
* @readonly
*/
High_1024x1024: number;
/**
* @zh 分辨率 2048 * 2048。
* @en shadow resolution 2048 * 2048.
* @readonly
*/
Ultra_2048x2048: number;
};
/**
* @zh 阴影类型。
* @en The shadow type
* @enum Shadows.ShadowType
*/
export const ShadowType: {
/**
* @zh 平面阴影。
* @en Planar shadow
* @property Planar
* @readonly
*/
Planar: number;
/**
* @zh 阴影贴图。
* @en Shadow type
* @property ShadowMap
* @readonly
*/
ShadowMap: number;
};
/**
* @zh pcf阴影等级。
* @en The pcf type
* @static
* @enum Shadows.PCFType
*/
export const PCFType: {
/**
* @zh x1 次采样
* @en x1 times
* @readonly
*/
HARD: number;
/**
* @zh x4 次采样
* @en x4 times
* @readonly
*/
SOFT: number;
/**
* @zh x9 次采样
* @en x9 times
* @readonly
*/
SOFT_2X: number;
/**
* @zh x16 次采样
* @en x16 times
* @readonly
*/
SOFT_4X: number;
};
/**
* @zh 级联阴影贴图层级。
* @en The CSM shadow level
* @enum Shadows.CSMLevel
*/
export const CSMLevel: {
/**
* @zh 1 个层级
* @en level 1
* @readonly
*/
LEVEL_1: number;
/**
* @zh 2 个层级
* @en level 2
* @readonly
*/
LEVEL_2: number;
/**
* @zh 3 个层级
* @en level 3
* @readonly
*/
LEVEL_3: number;
/**
* @zh 4 个层级
* @en level 4
* @readonly
*/
LEVEL_4: number;
};
/**
* @zh 级联阴影性能优化模式。
* @en The CSM performance optimization mode
* @enum Shadows.CSMOptimizationMode
*/
export const CSMOptimizationMode: {
/**
* @zh 没有性能优化
* @en has no performance optimization
* @readonly
*/
NONE: number;
/**
* @zh 剔除层与层之间重复物体
* @en Eliminate duplicate objects between layers
* @readonly
*/
RemoveDuplicates: number;
/**
* @zh 取消稳抖
* @en Disable rotation fix
* @readonly
*/
DisableRotationFix: number;
};
/**
* @en The global shadow's configuration of the render scene
* @zh 渲染场景的全局阴影配置
*/
export class Shadows {
/**
* @en MAX_FAR. This is shadow camera max far.
* @zh 阴影相机的最远视距。
*/
static readonly MAX_FAR: number;
/**
* @en EXPANSION_RATIO. This is shadow boundingBox Coefficient of expansion.
* @zh 阴影包围盒扩大系数。
*/
static readonly COEFFICIENT_OF_EXPANSION: number;
/**
* @en Whether activate planar shadow.
* @zh 是否启用平面阴影？
*/
get enabled(): boolean;
set enabled(val: boolean);
/**
* @en Shadow type.
* @zh 阴影类型。
*/
get type(): number;
set type(val: number);
/**
* @en The normal of the plane which receives shadow.
* @zh 阴影接收平面的法线。
*/
get normal(): math.Vec3;
set normal(val: math.Vec3);
/**
* @en The distance from coordinate origin to the receiving plane.
* @zh 阴影接收平面与原点的距离。
*/
get distance(): number;
set distance(val: number);
/**
* @en Positional offset values in planar shading calculations.
* @zh 平面阴影计算中的位置偏移值。
*/
get planeBias(): number;
set planeBias(val: number);
/**
* @en Shadow color.
* @zh 阴影颜色。
*/
get shadowColor(): math.Color;
set shadowColor(color: math.Color);
/**
* @en get or set shadow camera orthoSize.
* @zh 获取或者设置阴影纹理大小。
*/
get size(): math.Vec2;
set size(val: math.Vec2);
/**
* @en shadow Map size has been modified.
* @zh 阴影贴图大小是否被修改。
*/
get shadowMapDirty(): boolean;
set shadowMapDirty(val: boolean);
/**
* @en The transform matrix of the light source
* @zh 光源的变换矩阵
*/
get matLight(): math.Mat4;
get material(): Material;
get instancingMaterial(): Material;
/**
* @en The bounding sphere of the shadow map.
* @zh 用于计算固定区域阴影 Shadow map 的场景包围球.
*/
fixedSphere: geometry.Sphere;
/**
* @en get or set shadow max received.
* @zh 阴影接收的最大灯光数量。
*/
maxReceived: number;
protected _matLight: math.Mat4;
protected _material: Material | null;
protected _instancingMaterial: Material | null;
protected _enabled: boolean;
protected _type: number;
protected _distance: number;
protected _planeBias: number;
protected _normal: math.Vec3;
protected _shadowColor: math.Color;
protected _size: math.Vec2;
protected _shadowMapDirty: boolean;
/**
* @en Get the shader for the planar shadow with macro patches
* @zh 通过指定宏获取平面阴影的 Shader 对象
* @param patches The macro patches for the shader
* @returns The shader for the planar shadow
*/
getPlanarShader(patches: Readonly): gfx.Shader | null;
initialize(shadowsInfo: ShadowsInfo): void;
activate(): void;
protected _updatePlanarInfo(): void;
destroy(): void;
}
/**
* @zh
* 全局雾类型。
* @en
* The global fog type
* @static
* @enum FogInfo.FogType
*/
export const FogType: {
/**
* @zh
* 线性雾。
* @en
* Linear fog
* @readonly
*/
LINEAR: number;
/**
* @zh
* 指数雾。
* @en
* Exponential fog
* @readonly
*/
EXP: number;
/**
* @zh
* 指数平方雾。
* @en
* Exponential square fog
* @readonly
*/
EXP_SQUARED: number;
/**
* @zh
* 层叠雾。
* @en
* Layered fog
* @readonly
*/
LAYERED: number;
};
export const FOG_TYPE_NONE: number;
/**
* @en The fog representation in the render scene.
* @zh 渲染场景中的全局雾效配置
*/
export class Fog {
/**
* @zh 是否启用全局雾效
* @en Enable global fog
*/
set enabled(val: boolean);
get enabled(): boolean;
/**
* @zh 是否启用精确雾效(像素雾)计算
* @en Enable accurate fog (pixel fog)
*/
set accurate(val: boolean);
get accurate(): boolean;
/**
* @zh 全局雾颜色
* @en Global fog color
*/
set fogColor(val: math.Color);
get fogColor(): math.Color;
/**
* @zh 当前雾化类型。
* @en The current global fog type.
* @returns {FogType}
* Returns the current global fog type
* - -1:Disable global Fog
* - 0:Linear fog
* - 1:Exponential fog
* - 2:Exponential square fog
* - 3:Layered fog
*/
get type(): number;
set type(val: number);
/**
* @zh 全局雾浓度
* @en Global fog density
*/
get fogDensity(): number;
set fogDensity(val: number);
/**
* @zh 雾效起始位置，只适用于线性雾
* @en Global fog start position, only for linear fog
*/
get fogStart(): number;
set fogStart(val: number);
/**
* @zh 雾效结束位置，只适用于线性雾
* @en Global fog end position, only for linear fog
*/
get fogEnd(): number;
set fogEnd(val: number);
/**
* @zh 雾效衰减
* @en Global fog attenuation
*/
get fogAtten(): number;
set fogAtten(val: number);
/**
* @zh 雾效顶部范围，只适用于层级雾
* @en Global fog top range, only for layered fog
*/
get fogTop(): number;
set fogTop(val: number);
/**
* @zh 雾效范围，只适用于层级雾
* @en Global fog range, only for layered fog
*/
get fogRange(): number;
set fogRange(val: number);
get colorArray(): Readonly;
protected _fogColor: math.Color;
protected _colorArray: math.Vec4;
protected _enabled: boolean;
protected _accurate: boolean;
protected _type: number;
protected _fogDensity: number;
protected _fogStart: number;
protected _fogEnd: number;
protected _fogAtten: number;
protected _fogTop: number;
protected _fogRange: number;
protected _activated: boolean;
initialize(fogInfo: FogInfo): void;
activate(): void;
protected _updatePipeline(): void;
}
/**
* @en The octree culling configuration of the render scene
* @zh 渲染场景的八叉树剔除配置
*/
export class Octree {
/**
* @en Whether octree culling is enabled in the render scene
* @zh 是否开启八叉树加速剔除
*/
set enabled(val: boolean);
get enabled(): boolean;
/**
* @en Minimum position of the scene's bounding box
* @zh 场景包围盒最小值
*/
get minPos(): math.Vec3;
set minPos(val: math.Vec3);
/**
* @en Maximum position of the scene's bounding box
* @zh 场景包围盒最大值
*/
get maxPos(): math.Vec3;
set maxPos(val: math.Vec3);
/**
* @en The depth of the octree
* @zh 八叉树深度
*/
get depth(): number;
set depth(val: number);
protected _enabled: boolean;
protected _minPos: math.Vec3;
protected _maxPos: math.Vec3;
protected _depth: number;
initialize(octreeInfo: OctreeInfo): void;
}
/**
* @en Global skin in the render scene.
* The initial data is setup in [[SceneGlobals.skip]].
* @zh 渲染场景中的全局皮肤后处理设置。
* 初始值是由 [[SceneGlobals.skin]] 设置的。
*/
export class Skin {
/**
* @en Enable skip.
* @zh 是否开启皮肤后效。
*/
set enabled(val: boolean);
get enabled(): boolean;
/**
* @en Getter/Setter sampler width.
* @zh 设置或者获取采样宽度。
*/
set blurRadius(val: number);
get blurRadius(): number;
/**
* @en Getter/Setter depth unit scale.
* @zh 设置或者获取深度单位比例。
*/
set sssIntensity(val: number);
get sssIntensity(): number;
protected _enabled: boolean;
protected _blurRadius: number;
protected _sssIntensity: number;
initialize(skinInfo: SkinInfo): void;
}
export function ColorTemperatureToRGB(rgb: math.Vec3, kelvin: number): void;
/**
* @en The light type enumeration.
* @zh 光源类型枚举。
*/
export enum LightType {
DIRECTIONAL = 0,
SPHERE = 1,
SPOT = 2,
POINT = 3,
RANGED_DIRECTIONAL = 4,
UNKNOWN = 5
}
export const nt2lm: (size: number) => number;
/**
* @en The abstract light class of the render scene
* @zh 渲染场景中的光源基类
*/
export class Light {
/**
* @en Whether it's a baked light source, baked light will be ignored in real time lighting pass
* @zh 是否是烘焙光源，烘焙光源会在实时光照计算中被忽略
*/
get baked(): boolean;
set baked(val: boolean);
/**
* @en The color of the light
* @zh 光源的颜色
*/
set color(color: math.Vec3);
get color(): math.Vec3;
/**
* @en Whether to use color temperature
* @zh 是否使用光源的色温
*/
set useColorTemperature(enable: boolean);
get useColorTemperature(): boolean;
/**
* @en The color temperature of the light
* @zh 光源的色温
*/
set colorTemperature(val: number);
get colorTemperature(): number;
/**
* @en The float RGB value of the color temperature, each channel is from 0 to 1
* @zh 色温的浮点数颜色值，每个通道都是从 0 到 1
*/
get colorTemperatureRGB(): math.Vec3;
get finalColor(): Readonly;
set node(n: Node | null);
/**
* @en The node which owns the light source
* @zh 光源归属的节点
*/
get node(): Node | null;
/**
* @en The type of the light source, e.g. directional light, spot light, etc
* @zh 光源的类型，比如方向光、聚光灯等
*/
get type(): LightType;
/**
* @en The name of the light source
* @zh 光源的名字
*/
get name(): string | null;
set name(n: string | null);
/**
* @en The render scene which owns the current light
* @zh 光源所属的渲染场景
*/
get scene(): RenderScene | null;
protected _baked: boolean;
protected _color: math.Vec3;
protected _colorTemp: number;
protected _colorTempRGB: math.Vec3;
protected _scene: RenderScene | null;
protected _node: Node | null;
protected _name: string | null;
protected _useColorTemperature: boolean;
protected _type: LightType;
protected _visibility: number;
initialize(): void;
/**
* @en Attach the light to a render scene
* @zh 将光源挂载到渲染场景上
* @param scene @en The render scene @zh 渲染场景
*/
attachToScene(scene: RenderScene): void;
/**
* @en Detach the light from the render scene
* @zh 将光源从渲染场景上移除
*/
detachFromScene(): void;
destroy(): void;
update(): void;
}
/**
* @en The directional light representation in the render scene, it acts as the main light source in a scene.
* As main light, only one directional light can be created in a scene, it can generate realtime shadows with configuration.
* @zh 渲染场景中的方向光抽象，这是场景中的主光源。作为主光源，每个场景只能有一个方向光，它也包含阴影配置，用来生成实时阴影。
*/
export class DirectionalLight extends Light {
protected _dir: math.Vec3;
protected _illuminanceHDR: number;
protected _illuminanceLDR: number;
protected _shadowEnabled: boolean;
protected _shadowPcf: number;
protected _shadowBias: number;
protected _shadowNormalBias: number;
protected _shadowSaturation: number;
protected _shadowDistance: number;
protected _shadowInvisibleOcclusionRange: number;
protected _csmLevel: number;
protected _csmNeedUpdate: boolean;
protected _csmLayerLambda: number;
protected _csmOptimizationMode: number;
protected _csmLayersTransition: boolean;
protected _csmTransitionRange: number;
protected _shadowFixedArea: boolean;
protected _shadowNear: number;
protected _shadowFar: number;
protected _shadowOrthoSize: number;
/**
* @en The direction vector of the light
* @zh 光源的方向
*/
set direction(dir: math.Vec3);
get direction(): math.Vec3;
/**
* @en The illuminance of the light in Lux(lx)
* @zh 光源的辐照度，单位是 Lux(lx)
*/
get illuminance(): number;
set illuminance(value: number);
/**
* @en The illuminance of the light in HDR mode
* @zh HDR 模式下光源的辐照度
*/
get illuminanceHDR(): number;
set illuminanceHDR(value: number);
/**
* @en The illuminance of the light in LDR mode
* @zh LDR 模式下光源的辐照度
*/
get illuminanceLDR(): number;
set illuminanceLDR(value: number);
/**
* @en Whether activate shadow
* @zh 是否启用阴影？
*/
get shadowEnabled(): boolean;
set shadowEnabled(val: boolean);
/**
* @en get or set shadow pcf.
* @zh 获取或者设置阴影pcf等级。
*/
get shadowPcf(): number;
set shadowPcf(val: number);
/**
* @en get or set shadow map sampler offset
* @zh 获取或者设置阴影纹理偏移值
*/
get shadowBias(): number;
set shadowBias(val: number);
/**
* @en get or set normal bias.
* @zh 设置或者获取法线偏移。
*/
get shadowNormalBias(): number;
set shadowNormalBias(val: number);
/**
* @en Shadow color saturation
* @zh 阴影颜色饱和度
*/
get shadowSaturation(): number;
set shadowSaturation(val: number);
/**
* @en get or set shadow camera far
* @zh 获取或者设置潜在阴影产生的范围
*/
get shadowDistance(): number;
set shadowDistance(val: number);
/**
* @en get or set shadow camera far
* @zh 获取或者设置潜在阴影产生的范围
*/
get shadowInvisibleOcclusionRange(): number;
set shadowInvisibleOcclusionRange(val: number);
/**
* @en get or set shadow CSM level
* @zh 获取或者设置级联阴影层数
*/
get csmLevel(): number;
set csmLevel(val: number);
/**
* @en is CSM need update
* @zh 获取或者设置级联阴影是否需要更新
*/
get csmNeedUpdate(): boolean;
set csmNeedUpdate(val: boolean);
/**
* @en get or set shadow CSM level ratio
* @zh 获取或者设置级联阴影层数系数
*/
get csmLayerLambda(): number;
set csmLayerLambda(val: number);
/**
* @en get or set shadow CSM performance optimization mode
* @zh 获取或者设置级联阴影性能优化模式
*/
get csmOptimizationMode(): number;
set csmOptimizationMode(val: number);
/**
* @en get or set fixed area shadow
* @zh 是否是固定区域阴影
*/
get shadowFixedArea(): boolean;
set shadowFixedArea(val: boolean);
/**
* @en The near clip plane of the shadow camera
* @zh 获取或者设置阴影相机近裁剪面
*/
get shadowNear(): number;
set shadowNear(val: number);
/**
* @en The far clip plane of the shadow camera
* @zh 获取或者设置阴影相机远裁剪面
*/
get shadowFar(): number;
set shadowFar(val: number);
/**
* @en get or set shadow camera orthoSize
* @zh 获取或者设置阴影相机正交大小
*/
get shadowOrthoSize(): number;
set shadowOrthoSize(val: number);
/**
* @en Enabled csm layers transition
* @zh 是否启用级联阴影层级过渡？
*/
get csmLayersTransition(): boolean;
set csmLayersTransition(val: boolean);
/**
* @en get or set csm layers transition range
* @zh 获取或者设置级联阴影层级过渡范围？
*/
get csmTransitionRange(): number;
set csmTransitionRange(val: number);
constructor();
initialize(): void;
/**
* @en Update the direction
* @zh 更新方向
*/
update(): void;
}
/**
* @en The sphere light representation in the render scene, it will light up a spherical area in the scene.
* It doesn't support shadow generation currently.
* @zh 渲染场景中的球面光抽象，可以照亮场景中的一个球形区域，目前还不支持生成阴影。
*/
export class SphereLight extends Light {
/**
* @en The world position of the light source
* @zh 光源中心点的世界坐标
*/
get position(): math.Vec3;
/**
* @en The size of the light source
* @zh 球面光源的尺寸
*/
set size(size: number);
get size(): number;
/**
* @en The lighting range of the light source
* @zh 球面光源的光照范围
*/
set range(range: number);
get range(): number;
/**
* @en The luminance of the light source
* @zh 光源的亮度
*/
get luminance(): number;
set luminance(value: number);
/**
* @en The luminance of the light source in HDR mode
* @zh HDR 模式下光源的亮度
*/
get luminanceHDR(): number;
set luminanceHDR(value: number);
/**
* @en The luminance of the light source in LDR mode
* @zh LDR 模式下光源的亮度
*/
set luminanceLDR(value: number);
/**
* @en The AABB bounding box of the lighting area
* @zh 受光源影响范围的 AABB 包围盒
*/
get aabb(): geometry.AABB;
protected _needUpdate: boolean;
protected _size: number;
protected _range: number;
protected _luminanceHDR: number;
protected _luminanceLDR: number;
protected _pos: math.Vec3;
protected _aabb: geometry.AABB;
constructor();
initialize(): void;
/**
* @en Update the lighting area
* @zh 更新光源影响范围
*/
update(): void;
}
/**
* @en The spot light representation in the render scene, it will light up a cone area in the direction of the light, it supports shadow generation.
* @zh 渲染场景中的聚光灯抽象，可以照亮光源方向上的一个锥形区域，支持生成阴影。
*/
export class SpotLight extends Light {
protected _dir: math.Vec3;
protected _range: number;
protected _spotAngle: number;
protected _angleAttenuationStrength: number;
protected _pos: math.Vec3;
protected _aabb: geometry.AABB;
protected _frustum: geometry.Frustum;
/**
* @en User-specified full-angle radians.
* @zh 用户指定的全角弧度。
*/
protected _angle: number;
protected _needUpdate: boolean;
protected _size: number;
protected _luminanceHDR: number;
protected _luminanceLDR: number;
protected _shadowEnabled: boolean;
protected _shadowPcf: number;
protected _shadowBias: number;
protected _shadowNormalBias: number;
/**
* @en The world position of the light source
* @zh 光源的世界坐标
*/
get position(): math.Vec3;
/**
* @en The size of the spot light source
* @zh 聚光灯的光源尺寸
*/
set size(size: number);
get size(): number;
/**
* @en The lighting range of the spot light
* @zh 聚光灯的光照范围
*/
set range(range: number);
get range(): number;
/**
* @en The luminance of the light source
* @zh 光源的亮度
*/
get luminance(): number;
set luminance(value: number);
/**
* @en The luminance of the light source in HDR mode
* @zh HDR 模式下光源的亮度
*/
get luminanceHDR(): number;
set luminanceHDR(value: number);
/**
* @en The luminance of the light source in LDR mode
* @zh LDR 模式下光源的亮度
*/
get luminanceLDR(): number;
set luminanceLDR(value: number);
/**
* @en The direction of the spot light
* @zh 聚光灯的照明方向
*/
get direction(): math.Vec3;
/**
* @en The setter will take the value as the cone angle,
* but the getter will give you the cosine value of the half cone angle: `cos(angle / 2)`.
* As the in-consistence is not acceptable for a property, please do not use it.
* @zh 赋值时这个属性会把输入值当做聚光灯光照区域的锥角，但是获取时返回的是 cos(angle / 2)。
* 由于这种不一致性，请不要使用这个属性。
* @internal
*/
get spotAngle(): number;
set spotAngle(val: number);
/**
* @en The angle attenuation strength of the spot light.
* The larger the value, the softer the edge, and the smaller the value, the harder the edge.
* @zh 聚光灯角度衰减强度。值越大，边缘越柔和，值越小，边缘越硬。
*/
get angleAttenuationStrength(): number;
set angleAttenuationStrength(val: number);
/**
* @en The cone angle of the lighting area
* @zh 聚光灯锥角
*/
get angle(): number;
get aabb(): geometry.AABB;
/**
* @en The frustum of the lighting area
* @zh 受光源影响范围的截椎体
*/
get frustum(): geometry.Frustum;
/**
* @en Whether shadow casting is enabled
* @zh 是否启用阴影？
*/
get shadowEnabled(): boolean;
set shadowEnabled(val: boolean);
/**
* @en The pcf level of the shadow generation.
* @zh 获取或者设置阴影 pcf 等级。
*/
get shadowPcf(): number;
set shadowPcf(val: number);
/**
* @en The depth offset of shadow to avoid moire pattern artifacts
* @zh 阴影的深度偏移, 可以减弱跨像素导致的条纹状失真
*/
get shadowBias(): number;
set shadowBias(val: number);
/**
* @en The normal bias of the shadow map.
* @zh 设置或者获取法线偏移。
*/
get shadowNormalBias(): number;
set shadowNormalBias(val: number);
constructor();
initialize(): void;
update(): void;
}
/**
* @en The point light representation in the render scene, it will light up a spherical area in the scene.
* It doesn't support shadow generation currently.
* @zh 渲染场景中的点光抽象，可以照亮场景中的一个球形区域，目前还不支持生成阴影。
*/
export class PointLight extends Light {
/**
* @en The world position of the light source.
* @zh 光源中心点的世界坐标。
*/
get position(): Readonly;
/**
* @en The lighting range of the light source.
* @zh 点光源的光照范围。
*/
set range(range: number);
get range(): number;
/**
* @en The luminance of the light source.
* @zh 光源的亮度。
*/
get luminance(): number;
set luminance(value: number);
/**
* @en The luminance of the light source in HDR mode.
* @zh HDR 模式下光源的亮度。
*/
get luminanceHDR(): number;
set luminanceHDR(value: number);
/**
* @en The luminance of the light source in LDR mode.
* @zh LDR 模式下光源的亮度。
*/
set luminanceLDR(value: number);
/**
* @en The AABB bounding box of the lighting area.
* @zh 受光源影响范围的 AABB 包围盒。
*/
get aabb(): geometry.AABB;
constructor();
initialize(): void;
/**
* @en Update the lighting area.
* @zh 更新光源影响范围。
*/
update(): void;
}
/**
* @en Render the abstraction of light in the scene, which is a ranged directional light source in the scene. Non main light source,
* each scene is allowed to have multiple ranged directional light sources without shadows.
* @zh 渲染场景中的光的抽象，这是场景中的范围平行光光源。非主光源，每个场景允许有多个范围平行光光源，不包含阴影。
*/
export class RangedDirectionalLight extends Light {
/**
* @en The direction vector of the light
* @zh 光源的方向
*/
get direction(): Readonly;
/**
* @en The right vector of the light
* @zh 光源的右方向
*/
get right(): Readonly;
/**
* @en The world position of the light source
* @zh 光源的世界坐标
*/
get position(): Readonly;
/**
* @en The world scale of the light source
* @zh 光源的世界缩放
*/
get scale(): Readonly;
/**
* @en The illuminance of the light in Lux(lx)
* @zh 光源的辐照度，单位是 Lux(lx)
*/
get illuminance(): number;
set illuminance(value: number);
/**
* @en The illuminance of the light in HDR mode
* @zh HDR 模式下光源的辐照度
*/
get illuminanceHDR(): number;
set illuminanceHDR(value: number);
/**
* @en The illuminance of the light in LDR mode
* @zh LDR 模式下光源的辐照度
*/
get illuminanceLDR(): number;
set illuminanceLDR(value: number);
constructor();
initialize(): void;
/**
* @en Update
* @zh 更新
*/
update(): void;
}
export enum ProbeClearFlag {
SKYBOX,
SOLID_COLOR = 7
}
export enum ProbeType {
CUBE = 0,
PLANAR = 1
}
export class ReflectionProbe {
bakedCubeTextures: RenderTexture[];
realtimePlanarTexture: RenderTexture | null;
protected _resolution: number;
protected _clearFlag: number;
protected _backgroundColor: math.Color;
protected _visibility: number;
protected _probeType: ProbeType;
protected _cubemap: TextureCube | null;
protected readonly _size: math.Vec3;
/**
* @en Reflection probe cube pattern preview sphere
* @zh 反射探针cube模式的预览小球
*/
protected _previewSphere: Node | null;
protected _previewPlane: Node | null;
/**
* @en Set probe type,cube or planar.
* @zh 设置探针类型，cube或者planar
*/
set probeType(value: ProbeType);
get probeType(): ProbeType;
get resolution(): number;
/**
* @en set render texture size
* @zh 设置渲染纹理大小
*/
set resolution(value: number);
/**
* @en Clearing flags of the camera, specifies which part of the framebuffer will be actually cleared every frame.
* @zh 相机的缓冲清除标志位，指定帧缓冲的哪部分要每帧清除。
*/
set clearFlag(value: number);
get clearFlag(): number;
/**
* @en Clearing color of the camera.
* @zh 相机的颜色缓冲默认值。
*/
set backgroundColor(val: math.Color);
get backgroundColor(): math.Color;
/**
* @en Visibility mask, declaring a set of node layers that will be visible to this camera.
* @zh 可见性掩码，声明在当前相机中可见的节点层级集合。
*/
get visibility(): number;
set visibility(val: number);
/**
* @en Gets or sets the size of the box, in local space.
* @zh 获取或设置盒的大小。
*/
set size(value: math.Vec3);
get size(): math.Vec3;
set cubemap(val: TextureCube | null);
get cubemap(): TextureCube | null;
/**
* @en The node of the probe.
* @zh probe绑定的节点
*/
get node(): Node;
get camera(): Camera;
/**
* @en Refresh the objects that use this probe.
* @zh 刷新使用该probe的物体
*/
set needRefresh(value: boolean);
get needRefresh(): boolean;
set needRender(value: boolean);
get needRender(): boolean;
get boundingBox(): geometry.AABB | null;
set cameraNode(node: Node);
get cameraNode(): Node;
/**
* @en Reflection probe planar mode preview plane
* @zh 反射探针Planar模式的预览平面
*/
set previewPlane(val: Node);
get previewPlane(): Node;
constructor(id: number);
initialize(node: Node, cameraNode: Node): void;
initBakedTextures(): void;
captureCubemap(): void;
/**
* @en Render real-time planar reflection textures
* @zh 渲染实时平面反射贴图
* @param sourceCamera render planar reflection for this camera
*/
renderPlanarReflection(sourceCamera: Camera): void;
switchProbeType(type: ProbeType, sourceCamera: Camera | null): void;
getProbeId(): number;
updateProbeId(id: any): void;
renderArea(): math.Vec2;
isFinishedRendering(): boolean;
validate(): boolean;
destroy(): void;
enable(): void;
disable(): void;
updateCameraDir(faceIdx: number): void;
updateBoundingBox(): void;
hasFrameBuffer(framebuffer: gfx.Framebuffer): boolean;
isRGBE(): boolean;
}
export const ToneMappingType: {
DEFAULT: number;
LINEAR: number;
};
export class PostSettings {
protected _toneMappingType: number;
protected _activated: boolean;
set toneMappingType(val: number);
get toneMappingType(): number;
initialize(postSettingsInfo: PostSettingsInfo): void;
activate(): void;
protected _updatePipeline(): void;
}
}
export enum RenderQueue {
OPAQUE = 0,
TRANSPARENT = 1,
OVERLAY = 2
}
export enum PassStage {
DEFAULT = 1,
FORWARD = 2,
SHADOWCAST = 4
}
/**
* @en Gets the default values for the given type of uniform
* @zh 根据指定的 Uniform 类型来获取默认值
* @param type The type of the uniform
*/
export function getDefaultFromType(type: gfx.Type): readonly number[] | string;
export function getStringFromType(type: gfx.Type): string;
/**
* @en Override the preprocess macros
* @zh 覆写预处理宏
* @param target Target preprocess macros to be overridden
* @param source Preprocess macros used for override
*/
export function overrideMacros(target: MacroRecord, source: MacroRecord): boolean;
export const genHandle: (binding: number, type: gfx.Type, count: number, offset?: number) => number;
export const getTypeFromHandle: (handle: number) => number;
export const getBindingFromHandle: (handle: number) => number;
export const getCountFromHandle: (handle: number) => number;
export const getOffsetFromHandle: (handle: number) => number;
export const customizeType: (handle: number, type: gfx.Type) => number;
/**
* @en Vector type uniforms
* @zh 向量类型 uniform
*/
export type MaterialProperty = number | math.Vec2 | math.Vec3 | math.Vec4 | math.Color | math.Mat3 | math.Mat4 | math.Quat;
export const type2reader: {
0: (a: Float32Array, v: number, idx?: number) => void;
5: (a: Int32Array, v: number, idx?: number) => number;
6: (a: Int32Array, v: math.IVec2Like, idx?: number) => math.IVec2Like;
7: (a: Int32Array, v: math.IVec3Like, idx?: number) => math.IVec3Like;
8: (a: Int32Array, v: math.IVec4Like, idx?: number) => math.IVec4Like;
13: (a: Float32Array, v: number, idx?: number) => number;
14: (a: Float32Array, v: math.IVec2Like, idx?: number) => math.IVec2Like;
15: (a: Float32Array, v: math.IVec3Like, idx?: number) => math.IVec3Like;
16: (a: Float32Array, v: math.IVec4Like, idx?: number) => math.IVec4Like;
21: (a: Float32Array, v: math.IMat3Like, idx?: number) => math.IMat3Like;
25: (a: Float32Array, v: math.IMat4Like, idx?: number) => math.IMat4Like;
};
export const type2writer: {
0: (a: Float32Array, v: number, idx?: number) => void;
5: (a: Int32Array, v: number, idx?: number) => number;
6: (a: Int32Array, v: math.Vec2, idx?: number) => Int32Array;
7: (a: Int32Array, v: math.Vec3, idx?: number) => Int32Array;
8: (a: Int32Array, v: math.Vec4, idx?: number) => Int32Array;
13: (a: Float32Array, v: number, idx?: number) => number;
14: (a: Float32Array, v: math.Vec2, idx?: number) => Float32Array;
15: (a: Float32Array, v: math.Vec3, idx?: number) => Float32Array;
16: (a: Float32Array, v: math.Vec4, idx?: number) => Float32Array;
21: (a: Float32Array, v: math.Mat3, idx?: number) => Float32Array;
25: (a: Float32Array, v: math.Mat4, idx?: number) => Float32Array;
};
export const type2validator: {
5: (v: number) => boolean;
13: (v: number) => boolean;
6: (v: math.Vec2) => boolean;
14: (v: math.Vec2) => boolean;
7: (v: math.Vec3) => boolean;
15: (v: math.Vec3) => boolean;
8: (v: math.Vec4) => boolean;
16: (v: math.Vec4 | math.Color | math.Quat) => boolean;
21: (v: math.Mat3) => boolean;
25: (v: math.Mat4) => boolean;
};
/**
* @en Combination of preprocess macros
* @zh 预处理宏组合
*/
export type MacroRecord = Record;
export interface IPassInfoFull extends EffectAsset.IPassInfo {
passIndex: number;
defines: MacroRecord;
stateOverrides?: PassOverrides;
}
export type PassOverrides = __private.__types_globals__RecursivePartial;
export interface IMacroPatch {
name: string;
value: boolean | number | string;
}
export enum BatchingSchemes {
NONE = 0,
INSTANCING = 1
}
/**
* @en Render pass, store actual resources for the rendering process
* @zh 渲染 pass，储存实际描述绘制过程的各项资源。
*/
export class Pass {
/**
* @en Get the type of member in uniform buffer object with the handle
* @zh 根据 handle 获取 uniform 的具体类型。
*/
static getTypeFromHandle: (handle: number) => number;
/**
* @en Get the binding with handle
* @zh 根据 handle 获取 binding。
*/
static getBindingFromHandle: (handle: number) => number;
/**
* @en Get the array length with handle
* @zh 根据 handle 获取数组长度。
*/
static getCountFromHandle: (handle: number) => number;
protected static getOffsetFromHandle: (handle: number) => number;
/**
* @en Fill a pass represented by the given pass handle with the given override info
* @param hPass The pass handle point to the pass
* @param info The pass override info
*/
static fillPipelineInfo(pass: Pass, info: PassOverrides): void;
/**
* @en Get pass hash value by [[renderer.Pass]] hash information.
* @zh 根据 [[renderer.Pass]] 的哈希信息获取哈希值。
*
* @param hPass Handle of the pass info used to compute hash value.
*/
static getPassHash(pass: Pass): number;
protected _rootBuffer: gfx.Buffer | null;
protected _buffers: gfx.Buffer[];
protected _descriptorSet: gfx.DescriptorSet;
protected _pipelineLayout: gfx.PipelineLayout;
protected _passIndex: number;
protected _propertyIndex: number;
protected _programName: string;
protected _dynamics: __private._cocos_render_scene_core_pass__IPassDynamics;
protected _propertyHandleMap: Record;
protected _rootBlock: ArrayBuffer | null;
protected _blocksInt: Int32Array[];
protected _blocks: Float32Array[];
protected _shaderInfo: IProgramInfo;
protected _defines: MacroRecord;
protected _properties: Record;
protected _shader: gfx.Shader | null;
protected _bs: gfx.BlendState;
protected _dss: gfx.DepthStencilState;
protected _rs: gfx.RasterizerState;
protected _priority: pipeline.RenderPriority;
protected _stage: pipeline.RenderPassStage;
protected _phase: number;
protected _passID: number;
protected _subpassID: number;
protected _phaseID: number;
protected _primitive: gfx.PrimitiveMode;
protected _batchingScheme: BatchingSchemes;
protected _dynamicStates: gfx.DynamicStateFlagBit;
protected _instancedBuffers: Record;
protected _hash: number;
protected _root: Root;
protected _device: gfx.Device;
protected _rootBufferDirty: boolean;
constructor(root: Root);
/**
* @en Initialize the pass with given pass info, shader will be compiled in the init process
* @zh 根据指定参数初始化当前 pass，shader 会在这一阶段就尝试编译。
*/
initialize(info: IPassInfoFull): void;
/**
* @en Get the handle of a UBO member, or specific channels of it.
* @zh 获取指定 UBO 成员，或其更具体分量的读写句柄。默认以成员自身的类型为目标读写类型（即读写时必须传入与成员类型相同的变量）。
* @param name Name of the target UBO member.
* @param offset Channel offset into the member.
* @param targetType Target type of the handle, i.e. the type of data when read/write to it.
* @example
* ```
* import { Vec3, gfx } from 'cc';
* // say 'pbrParams' is a uniform vec4
* const hParams = pass.getHandle('pbrParams'); // get the default handle
* pass.setUniform(hAlbedo, new Vec3(1, 0, 0)); // wrong! pbrParams.w is NaN now
*
* // say 'albedoScale' is a uniform vec4, and we only want to modify the w component in the form of a single float
* const hThreshold = pass.getHandle('albedoScale', 3, gfx.Type.FLOAT);
* pass.setUniform(hThreshold, 0.5); // now, albedoScale.w = 0.5
* ```
*/
getHandle(name: string, offset?: number, targetType?: gfx.Type): number;
/**
* @en Gets the uniform binding with its name
* @zh 获取指定 uniform 的 binding。
* @param name The name of target uniform
*/
getBinding(name: string): number;
/**
* @en Sets a vector type uniform value, if a uniform requires frequent update, please use this method.
* @zh 设置指定普通向量类 uniform 的值，如果需要频繁更新请尽量使用此接口。
* @param handle The handle for the target uniform
* @param value New value
*/
setUniform(handle: number, value: MaterialProperty): void;
/**
* @en Gets a uniform's value.
* @zh 获取指定普通向量类 uniform 的值。
* @param handle The handle for the target uniform
* @param out The output property to store the result
*/
getUniform(handle: number, out: T): T;
/**
* @en Sets an array type uniform value, if a uniform requires frequent update, please use this method.
* @zh 设置指定数组类 uniform 的值，如果需要频繁更新请尽量使用此接口。
* @param handle The handle for the target uniform
* @param value New value
*/
setUniformArray(handle: number, value: MaterialProperty[]): void;
/**
* @en Bind a GFX [[gfx.Texture]] the the given uniform binding
* @zh 绑定实际 GFX [[gfx.Texture]] 到指定 binding。
* @param binding The binding for target uniform of texture type
* @param value Target texture
*/
bindTexture(binding: number, value: gfx.Texture, index?: number): void;
/**
* @en Bind a GFX [[gfx.Sampler]] the the given uniform binding
* @zh 绑定实际 GFX [[gfx.Sampler]] 到指定 binding。
* @param binding The binding for target uniform of sampler type
* @param value Target sampler
*/
bindSampler(binding: number, value: gfx.Sampler, index?: number): void;
/**
* @en Sets the dynamic pipeline state property at runtime
* @zh 设置运行时 pass 内可动态更新的管线状态属性。
* @param state Target dynamic state
* @param value Target value
*/
setDynamicState(state: gfx.DynamicStateFlagBit, value: number): void;
/**
* @en Override all pipeline states with the given pass override info.
* @zh 重载当前所有管线状态。
* @param original The original pass info
* @param value The override pipeline state info
*/
overridePipelineStates(original: EffectAsset.IPassInfo, overrides: PassOverrides): void;
/**
* @en Update the current uniforms data.
* @zh 更新当前 Uniform 数据。
*/
update(): void;
getInstancedBuffer(extraKey?: number): InstancedBuffer;
/**
* @en Destroy the current pass.
* @zh 销毁当前 pass。
*/
destroy(): void;
/**
* @en Resets the value of the given uniform by name to the default value in [[EffectAsset]].
* This method does not support array type uniform.
* @zh 重置指定（非数组） Uniform 为 [[EffectAsset]] 默认值。
*/
resetUniform(name: string): void;
/**
* @en Resets the value of the given texture by name to the default value in [[EffectAsset]].
* @zh 重置指定贴图为 [[EffectAsset]] 默认值。
*/
resetTexture(name: string, index?: number): void;
/**
* @en Resets all uniform buffer objects to the default values in [[EffectAsset]]
* @zh 重置所有 UBO 为默认值。
*/
resetUBOs(): void;
/**
* @en Resets all textures and samplers to the default values in [[EffectAsset]]
* @zh 重置所有 texture 和 sampler 为初始默认值。
*/
resetTextures(): void;
/**
* @en Try to compile the shader and retrieve related resources references.
* @zh 尝试编译 shader 并获取相关资源引用。
*/
tryCompile(): boolean;
/**
* @en Gets the shader variant of the current pass and given macro patches
* @zh 结合指定的编译宏组合获取当前 Pass 的 Shader Variant
* @param patches The macro patches
*/
getShaderVariant(patches?: Readonly): gfx.Shader | null;
protected get _isBlend(): boolean;
/**
* @private
*/
beginChangeStatesSilently(): void;
/**
* @private
*/
endChangeStatesSilently(): void;
protected _doInit(info: IPassInfoFull, copyDefines?: boolean): void;
protected _syncBatchingScheme(): void;
get root(): Root;
get device(): gfx.Device;
get shaderInfo(): IProgramInfo;
get localSetLayout(): gfx.DescriptorSetLayout;
get program(): string;
get properties(): Record;
get defines(): Record;
get passIndex(): number;
get propertyIndex(): number;
get dynamics(): __private._cocos_render_scene_core_pass__IPassDynamics;
get blocks(): Float32Array[];
get blocksInt(): Int32Array[];
get rootBufferDirty(): boolean;
get priority(): pipeline.RenderPriority;
get primitive(): gfx.PrimitiveMode;
get stage(): pipeline.RenderPassStage;
get phase(): number;
get passID(): number;
get phaseID(): number;
get rasterizerState(): gfx.RasterizerState;
get depthStencilState(): gfx.DepthStencilState;
get blendState(): gfx.BlendState;
get dynamicStates(): gfx.DynamicStateFlags;
get batchingScheme(): BatchingSchemes;
get descriptorSet(): gfx.DescriptorSet;
get hash(): number;
get pipelineLayout(): gfx.PipelineLayout;
}
export namespace Pass {
export type getTypeFromHandle = typeof Pass.getTypeFromHandle;
export type getBindingFromHandle = typeof Pass.getBindingFromHandle;
export type fillPipelineInfo = typeof Pass.fillPipelineInfo;
export type getPassHash = typeof Pass.getPassHash;
export type getCountFromHandle = typeof Pass.getCountFromHandle;
}
export function nearestPOT(num: number): number;
export interface ITextureBuffer {
texture: gfx.Texture;
size: number;
start: number;
end: number;
}
export interface ITextureBufferHandle {
chunkIdx: number;
start: number;
end: number;
texture: gfx.Texture;
}
export interface ITextureBufferPoolInfo {
format: gfx.Format;
inOrderFree?: boolean;
alignment?: number;
roundUpFn?: (size: number, formatSize: number) => number;
}
export class TextureBufferPool {
constructor(device: gfx.Device);
initialize(info: ITextureBufferPoolInfo): void;
destroy(): void;
alloc(size: number, chunkIdx?: number): ITextureBufferHandle;
free(handle: ITextureBufferHandle): void;
createChunk(length: number): number;
update(handle: ITextureBufferHandle, buffer: ArrayBuffer): void;
}
export interface IMaterialInstanceInfo {
parent: Material;
owner?: Renderer;
subModelIdx?: number;
}
/**
* @zh
* 材质实例，当有材质修改需求时，根据材质资源创建的，可任意定制的实例。
*/
export class MaterialInstance extends Material {
get parent(): Material;
get owner(): Renderer | null;
protected _passes: PassInstance[];
constructor(info: IMaterialInstanceInfo);
recompileShaders(overrides: MacroRecord, passIdx?: number): void;
overridePipelineStates(overrides: PassOverrides, passIdx?: number): void;
destroy(): boolean;
onPassStateChange(dontNotify: boolean): void;
protected _createPasses(): PassInstance[];
}
/**
* @en A pass instance defines an variant version of the [[renderer.Pass]]
* @zh 表示 [[renderer.Pass]] 的一种特殊实例
*/
export class PassInstance extends Pass {
/**
* @en The parent pass
* @zh 相关联的原始 Pass
*/
get parent(): Pass;
constructor(parent: Pass, owner: MaterialInstance);
/**
* @en Override pipeline states with the given pass override info.
* This won't affect the original pass
* @zh 重载当前 Pass 的管线状态。这不会影响原始 Pass
* @param original The original pass info
* @param value The override pipeline state info
*/
overridePipelineStates(original: EffectAsset.IPassInfo, overrides: PassOverrides): void;
tryCompile(defineOverrides?: MacroRecord): boolean;
/**
* @en Prepare to change states of the pass and do not notify the material to rebuild the pipeline state object
* @zh 开始静默修改 Pass 相关状态，不会通知材质去重新构建管线状态对象。
*/
beginChangeStatesSilently(): void;
/**
* @en End the silent states changing process, all state changes will be notified.
* @zh 结束静默状态修改，所有修改将会开始通知材质。
*/
endChangeStatesSilently(): void;
protected _syncBatchingScheme(): void;
protected _onStateChange(): void;
}
export enum PoolType {
NODE = 0,
PASS = 1,
AABB = 2,
RENDER2D = 3
}
export const NULL_HANDLE: __private._cocos_render_scene_core_memory_pools__IHandle;
export type Render2dHandle = __private._cocos_render_scene_core_memory_pools__IHandle;
export enum Render2dView {
POSITION = 0,
UV = 3,
COLOR = 5,
COUNT = 9
}
export const Render2dPool: __private._cocos_render_scene_core_memory_pools__BufferPool;
export type NodeHandle = __private._cocos_render_scene_core_memory_pools__IHandle;
export enum NodeView {
DIRTY_FLAG = 0,
LAYER = 1,
WORLD_SCALE = 2,
WORLD_POSITION = 5,
WORLD_ROTATION = 8,
WORLD_MATRIX = 12,
LOCAL_SCALE = 28,
LOCAL_POSITION = 31,
LOCAL_ROTATION = 34,
COUNT = 38
}
export const NodePool: __private._cocos_render_scene_core_memory_pools__BufferPool;
export type PassHandle = __private._cocos_render_scene_core_memory_pools__IHandle;
export enum PassView {
PRIORITY = 0,
STAGE = 1,
PHASE = 2,
PRIMITIVE = 3,
BATCHING_SCHEME = 4,
DYNAMIC_STATE = 5,
HASH = 6,
COUNT = 7
}
export const PassPool: __private._cocos_render_scene_core_memory_pools__BufferPool;
export type AABBHandle = __private._cocos_render_scene_core_memory_pools__IHandle;
export enum AABBView {
CENTER = 0,
HALFEXTENTS = 3,
COUNT = 6
}
export const AABBPool: __private._cocos_render_scene_core_memory_pools__BufferPool;
export interface IRenderSceneInfo {
name: string;
}
export interface ISceneNodeInfo {
name: string;
isStatic?: boolean;
}
/**
* @en The result of one raycast operation
* @zh 一次射线检测的结果
*/
export interface IRaycastResult {
node: Node;
distance: number;
}
/**
* @en The render scene which is created by the [[Root]] and provides all basic render scene elements for the render process.
* It manages:
* 1. [[Camera]]s
* 2. [[Light]]s
* 3. Renderable objects: [[renderer.Model]]s and `DrawBatchs`
* @zh 渲染场景，由 [[Root]] 创建，并提供用于渲染流程的所有场景基础元素。它管理：
* 1. [[Camera]]s：相机
* 2. [[Light]]s：光源
* 3. 渲染元素：[[renderer.Model]]s 和 `DrawBatchs`
*/
export class RenderScene {
/**
* @en The root manager of the renderer.
* @zh 基础渲染管理器。
*/
get root(): Root;
/**
* @en The name of the render scene.
* @zh 渲染场景的名称。
*/
get name(): string;
/**
* @en All cameras of the render scene.
* @zh 渲染场景管理的所有相机。
*/
get cameras(): scene.Camera[];
/**
* @en The main directional light source of the render scene.
* @zh 渲染场景管理的主方向光源。
*/
get mainLight(): scene.DirectionalLight | null;
/**
* @en All sphere light sources of the render scene.
* @zh 渲染场景管理的所有球面光源。
*/
get sphereLights(): Readonly;
/**
* @en All spot light sources of the render scene.
* @zh 渲染场景管理的所有聚光灯光源。
*/
get spotLights(): Readonly;
/**
* @en All point light sources of the render scene.
* @zh 渲染场景管理的所有点光源。
*/
get pointLights(): Readonly;
/**
* @en All ranged directional light sources of the render scene.
* @zh 渲染场景管理的所有范围平行光光源。
*/
get rangedDirLights(): Readonly;
/**
* @en All active models of the render scene.
* @zh 渲染场景管理的所有模型。
*/
get models(): scene.Model[];
/**
* @en All active 2d draw batches of the render scene.
* @zh 渲染场景管理的所有 2D 渲染批次对象。
*/
get batches(): __private._cocos_2d_renderer_draw_batch__DrawBatch2D[];
/**
* Register the creation function of the render scene to root.
* @internal
*/
static registerCreateFunc(root: Root): void;
constructor(root: Root);
/**
* @en Initialize the render scene
* @zh 初始化渲染场景
* @returns Successful
*/
initialize(info: IRenderSceneInfo): boolean;
/**
* @en The update process of the render scene, it updates all rendering related data for the lights and the models.
* @zh 渲染场景的更新流程，会更新所有光源和模型的渲染相关数据。
* @param stamp The update time stamp
* @returns void
*/
update(stamp: number): void;
/**
* @en Destroy the render scene, dangerous, please do not invoke manually.
* @zh 销毁渲染场景，请不要手动销毁，会造成未知行为。
*/
destroy(): void;
isCulledByLod(camera: scene.Camera, model: scene.Model): boolean;
/**
* @en Attach a camera to the render scene
* @zh 向渲染场景挂载一个相机
*/
addCamera(cam: scene.Camera): void;
/**
* @en Detach a camera to the render scene
* @zh 从渲染场景移除一个相机
*/
removeCamera(camera: scene.Camera): void;
/**
* @en Detach all cameras to the render scene
* @zh 从渲染场景移除所有相机
*/
removeCameras(): void;
/**
* @en Sets the main light source for the render scene
* @zh 给渲染场景设置主光源
* @param dl The main directional light source
*/
setMainLight(dl: scene.DirectionalLight | null): void;
/**
* @en Remove the main light source from the render scene
* @zh 从渲染场景移除主光源
* @param dl The main directional light source, if it's not the actual main light, nothing happens.
*/
unsetMainLight(dl: scene.DirectionalLight): void;
/**
* @en Add a directional light source, only one directional light is active and act as the main light source.
* @zh 增加一个方向光源，场景中只会有一个方向光是起效的，并且会作为主光源。
* @param dl The directional light.
*/
addDirectionalLight(dl: scene.DirectionalLight): void;
/**
* @en Remove a directional light source.
* @zh 删除一个方向光源。
* @param dl The directional light.
*/
removeDirectionalLight(dl: scene.DirectionalLight): void;
/**
* @en Add a sphere light source.
* @zh 增加一个球面光源。
* @param pl The sphere light.
*/
addSphereLight(pl: scene.SphereLight): void;
/**
* @en Remove a sphere light source.
* @zh 删除一个球面光源。
* @param pl The sphere light.
*/
removeSphereLight(pl: scene.SphereLight): void;
/**
* @en Add a spot light source.
* @zh 增加一个聚光灯光源。
* @param sl The spot light.
*/
addSpotLight(sl: scene.SpotLight): void;
/**
* @en Remove a spot light source.
* @zh 删除一个聚光灯光源。
* @param sl The spot light.
*/
removeSpotLight(sl: scene.SpotLight): void;
/**
* @en Remove all sphere light sources.
* @zh 删除所有球面光源。
*/
removeSphereLights(): void;
/**
* @en Remove all spot light sources.
* @zh 删除所有聚光灯光源。
*/
removeSpotLights(): void;
/**
* @en Add a point light source.
* @zh 增加一个点光源。
* @param pl @en The point light. @zh 点光源。
*/
addPointLight(pl: scene.PointLight): void;
/**
* @en Remove a sphere light source.
* @zh 删除一个点光源。
* @param pl @en The point light. @zh 点光源。
*/
removePointLight(pl: scene.PointLight): void;
/**
* @en Remove all point light sources.
* @zh 删除所有点光源。
*/
removePointLights(): void;
/**
* @en Add a ranged directional light source.
* @zh 增加一个范围平行光源。
* @param l @en The ranged directional light. @zh 范围平行光。
*/
addRangedDirLight(l: scene.RangedDirectionalLight): void;
/**
* @en Remove a ranged directional light source.
* @zh 删除一个范围平行光源。
* @param l @en The ranged directional light. @zh 范围平行光。
*/
removeRangedDirLight(l: scene.RangedDirectionalLight): void;
/**
* @en Remove all ranged directional light sources.
* @zh 删除所有范围平行光源。
*/
removeRangedDirLights(): void;
/**
* @en Add a model, all models attached to the render scene will be submitted for rendering.
* @zh 增加一个模型，渲染场景上挂载的所有模型都会被提交渲染。
* @param m The model.
*/
addModel(m: scene.Model): void;
/**
* @en Remove a model, model removed will no longer be submitted for rendering.
* @zh 删除一个模型，移除的模型将不再被提交渲染。
* @param m The model.
*/
removeModel(model: scene.Model): void;
/**
* @en Remove all models.
* @zh 删除所有模型。
*/
removeModels(): void;
/**
* @en Add a draw batch of 2d objects, all draw batches attached to the render scene will be submitted for rendering.
* @zh 增加一个 2D 渲染批次，渲染场景上挂载的所有 2D 渲染批次都会被提交渲染。
* @param batch The draw batch.
* @internal
* @deprecated since v3.6.0, this is an engine private interface that will be removed in the future.
*/
addBatch(batch: __private._cocos_2d_renderer_draw_batch__DrawBatch2D): void;
/**
* @en Remove a draw batch of 2d objects, draw batch removed will no longer be submitted for rendering.
* @zh 删除一个 2D 渲染批次，移除的 2D 渲染批次将不再被提交渲染。
* @param batch The draw batch.
* @internal
* @deprecated since v3.6.0, this is an engine private interface that will be removed in the future.
*/
removeBatch(batch: __private._cocos_2d_renderer_draw_batch__DrawBatch2D): void;
/**
* @en Remove all 2d draw batches.
* @zh 删除所有 2D 渲染批次。
* @internal
* @deprecated since v3.6.0, this is an engine private interface that will be removed in the future.
*/
removeBatches(): void;
/**
* @en Notify all models that the global pipeline state have been updated so that they can update their render data and states.
* @zh 通知所有模型全局管线状态已更新，需要更新自身状态。
*/
onGlobalPipelineStateChanged(): void;
/**
* @en Generate a new model id.
* @zh 生成一个新的模型 ID
* @returns The model id
*/
generateModelId(): number;
}
export const CameraVisFlags: {};
export const VisibilityFlags: {};
}
export type Constructor = __private.__types_globals__Constructor;
export namespace math {
export namespace bits {
/**
* @en Returns -1, 0, +1 depending on sign of x.
* @zh 根据x的符号返回 -1，0，+1。
*/
export function sign(v: number): number;
/**
* @en Computes absolute value of integer.
* @zh 计算整数的绝对值。
*/
export function abs(v: number): number;
/**
* @en Computes minimum of integers x and y.
* @zh 计算整数x和y中的最小值。
*/
export function min(x: number, y: number): number;
/**
* @en Computes maximum of integers x and y.
* @zh 计算整数x和y中的最大值。
*/
export function max(x: number, y: number): number;
/**
* @en Checks if a number is a power of two.
* @zh 检查一个数字是否是2的幂。
*/
export function isPow2(v: number): boolean;
/**
* @en Computes log base 2 of v.
* @zh 计算以 2 为底的 v 的对数。
*/
export function log2(v: number): number;
/**
* @en Computes log base 10 of v.
* @zh 计算以 10 为底的 v 的对数。
*/
export function log10(v: number): number;
/**
* @en Counts number of bits.
* @zh 计算传入数字二进制表示中 1 的数量。
*/
export function popCount(v: number): number;
/**
* @en Counts number of trailing zeros.
* @zh 计算传入数字二进制表示尾随零的数量。
*/
export function countTrailingZeros(v: number): number;
/**
* @en Rounds to next power of 2.
* @zh 计算大于等于v的最小的二的整数次幂的数字。
*/
export function nextPow2(v: number): number;
/**
* @en Rounds down to previous power of 2.
* @zh 计算小于等于v的最小的二的整数次幂的数字。
*/
export function prevPow2(v: number): number;
/**
* @en Computes parity of word.
* @zh 奇偶校验。
*/
export function parity(v: number): number;
/**
* @en Reverse bits in a 32 bit word.
* @zh 翻转 32 位二进制数字。
*/
export function reverse(v: number): number;
/**
* @en Interleave bits of 2 coordinates with 16 bits. Useful for fast quadtree codes.
* @zh 将两个 16 位数字按位交错编码。有利于在快速四叉树中使用。
*/
export function interleave2(x: number, y: number): number;
/**
* @en Extracts the nth interleaved component.
* @zh 提取第 n 个交错分量。
*/
export function deinterleave2(v: number, n: number): number;
/**
* @en Interleave bits of 3 coordinates, each with 10 bits. Useful for fast octree codes.
* @zh 将三个数字按位交错编码，每个数字占十位。有利于在八叉树中使用。
*/
export function interleave3(x: number, y: number, z: number): number;
/**
* @en Extracts nth interleaved component of a 3-tuple.
* @zh 提取三个数字中的第n个交错分量。
*/
export function deinterleave3(v: number, n: number): number;
/**
* @en Compute the lexicographically next bit permutation
* @zh 计算下一组字典序的比特排列
*/
export function nextCombination(v: number): number;
/**
* Bit twiddling hacks for JavaScript.
*
* Author: Mikola Lysenko
*
* Ported from Stanford bit twiddling hack library:
* http://graphics.stanford.edu/~seander/bithacks.html
*/
/**
* @en
* Number of bits in an integer
* @zh
* 整型类型的 bit 数
*/
export const INT_BITS = 32;
/**
* @en
* The maximal signed integer number
* @zh
* 最大有符号整型数
*/
export const INT_MAX = 2147483647;
/**
* @en
* The minimal signed integer number
* @zh
* 最小有符号整型数
*/
export const INT_MIN: number;
}
/**
* @en Representation of 2D vectors and points.
* @zh 二维向量。
*/
export class Vec2 extends ValueType {
static ZERO: Readonly