资产 / 图像 / RenderTexture节点

学习目标

读取和验证 Cocos 资产对象，把图片、音频、材质、Prefab 等资源接入工作流逻辑。

覆盖范围

• 节点数量：7
• 分类路径：资产 / 图像 / RenderTexture

典型使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

通用注意事项

• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

节点索引

节点	节点 ID	输入/输出	执行方式
初始化渲染纹理	renderTextureInitialize	3 / 2	立即继续
调整尺寸	renderTextureResize	4 / 2	立即继续
读取像素数据	renderTextureReadPixels	7 / 2	立即继续
获取渲染窗口	renderTextureGetWindow	1 / 1	立即继续
设置渲染纹理属性	renderTextureSetProperties	9 / 2	立即继续
新建渲染纹理	renderTextureCreate	1 / 2	立即继续
重置渲染纹理	renderTextureReset	3 / 2	立即继续

初始化渲染纹理

初始化 RenderTexture：调用 initialize(info)，使用 IRenderTextureCreateInfo 结构体完成渲染纹理的全量初始化。 通常在 RenderTexture Create 之后立即使用，指定宽高、渲染通道配置（passInfo）和外部资产句柄等所有参数。 如果渲染纹理已经初始化过，建议改用 RenderTexture Reset 重新配置。

节点信息

字段	值
节点 ID	renderTextureInitialize
分类	资产
二级分类	图像
分组	RenderTexture
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
renderTexture	渲染纹理	数据	cc.Asset / RenderTexture	RenderTexture 渲染纹理 这里需要连接一个已加载或已创建的 RenderTexture 实例。 该端口没有”选择渲染纹理”按钮，请先使用以下方式获取 RenderTexture 实例： - 加载资产：把”类型”选为 RENDER_TEXTURE，从资产包按路径异步加载已有 .rt 文件。 - 获取资产：取出资产包里已加载的 RenderTexture。 - 新建渲染纹理：游戏运行时创建新实例，再用 初始化渲染纹理 初始化。	-	必填
info	初始化参数	数据	any	初始化参数 描述渲染纹理的配置结构体，包含 name（名称）、width（宽度）、height（高度）、passInfo（渲染通道配置，可选）、externalResLow / externalResHigh / externalFlag（外部资产句柄，高级用法）。请先用 Make IRenderTextureCreateInfo 节点构造该结构体，再连接到此处。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
renderTexture	渲染纹理	数据	cc.Asset / RenderTexture	RenderTexture（透传） 把当前操作的 RenderTexture 实例原样传出，便于将多个配置节点串联在一起。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

调整尺寸

调整尺寸：调用 resize(width, height)，快速调整渲染纹理的宽度和高度，而无需重新构造完整的 IRenderTextureCreateInfo。 适合动态分辨率调整、截图尺寸设置等场景——只关心尺寸变化，不需要修改渲染通道配置或外部资产句柄。 如果需要同时更改渲染通道配置，请改用 RenderTexture Reset 并提供完整的 IRenderTextureCreateInfo。

节点信息

字段	值
节点 ID	renderTextureResize
分类	资产
二级分类	图像
分组	RenderTexture
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
renderTexture	渲染纹理	数据	cc.Asset / RenderTexture	RenderTexture 渲染纹理 这里需要连接一个已加载或已创建的 RenderTexture 实例。 该端口没有”选择渲染纹理”按钮，请先使用以下方式获取 RenderTexture 实例： - 加载资产：把”类型”选为 RENDER_TEXTURE，从资产包按路径异步加载已有 .rt 文件。 - 获取资产：取出资产包里已加载的 RenderTexture。 - 新建渲染纹理：游戏运行时创建新实例，再用 初始化渲染纹理 初始化。	-	必填
width	宽度	数据	number	宽度 新的渲染纹理宽度（像素，正整数）。	输入框 默认值：512	必填
height	高度	数据	number	高度 新的渲染纹理高度（像素，正整数）。	输入框 默认值：512	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
renderTexture	渲染纹理	数据	cc.Asset / RenderTexture	RenderTexture（透传） 把当前操作的 RenderTexture 实例原样传出，便于将多个配置节点串联在一起。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

读取像素数据

读取像素数据：调用 readPixels(x, y, width, height, buffer)，从渲染纹理的指定矩形区域读取 RGBA 原始像素数据（每像素 4 字节）。 参数说明：

• x / y：读取起点（像素），默认 0（左上角）。
• width / height：读取区域尺寸。设为 0 或负数时，自动使用渲染纹理的完整尺寸，避免硬编码错误区域。
• buffer（可选）：复用已有 Uint8Array 缓冲区。若不提供，游戏运行时自动分配；若提供但长度不足，返回 null。 注意：像素总字节数约为 width × height × 4。对大分辨率渲染纹理进行完整读取可能产生较大内存开销，建议按需读取局部区域。 该节点有执行流，确保在渲染帧完成后调用，避免读取到未完成的帧缓冲。

节点信息

字段	值
节点 ID	renderTextureReadPixels
分类	资产
二级分类	图像
分组	RenderTexture
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
renderTexture	渲染纹理	数据	cc.Asset / RenderTexture	RenderTexture 渲染纹理 这里需要连接一个已加载或已创建的 RenderTexture 实例。 该端口没有”选择渲染纹理”按钮，请先使用以下方式获取 RenderTexture 实例： - 加载资产：把”类型”选为 RENDER_TEXTURE，从资产包按路径异步加载已有 .rt 文件。 - 获取资产：取出资产包里已加载的 RenderTexture。 - 新建渲染纹理：游戏运行时创建新实例，再用 初始化渲染纹理 初始化。	-	必填
x	起点 X	数据	number	起点 X 读取区域左上角的水平坐标（像素）。默认 0。	输入框 默认值：0	可选
y	起点 Y	数据	number	起点 Y 读取区域左上角的垂直坐标（像素）。默认 0。	输入框 默认值：0	可选
width	宽度	数据	number	宽度 读取区域的宽度（像素）。设为 0 或负数时自动使用渲染纹理的完整宽度，避免硬编码错误区域。	输入框 默认值：0	可选
height	高度	数据	number	高度 读取区域的高度（像素）。设为 0 或负数时自动使用渲染纹理的完整高度，避免硬编码错误区域。	输入框 默认值：0	可选
buffer	缓冲区	数据	reference / Uint8Array	缓冲区 可复用的像素缓冲区。如不提供，游戏运行时自动分配新缓冲区。如提供但长度不足（需 ≥ width × height × 4 字节），游戏运行时返回 null 而非写入越界数据。	-	可选

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
pixels	像素数据	数据	reference / Uint8Array	像素数据 RGBA 原始像素数组（每像素 4 字节）。buffer 长度不足时为 null。总字节数 ≈ width × height × 4。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

获取渲染窗口

获取渲染窗口：读出当前 RenderTexture 关联的渲染窗口（renderer.RenderWindow）。 RenderWindow 是相机与渲染目标之间的关联对象，封装了渲染目标的宽高、相机绑定与调整大小接口。可将输出连接到 渲染窗口节点 系列进行进一步操作。 该节点是纯数据节点，不产生副作用。

节点信息

字段	值
节点 ID	renderTextureGetWindow
分类	资产
二级分类	图像
分组	RenderTexture
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
renderTexture	渲染纹理	数据	cc.Asset / RenderTexture	RenderTexture 渲染纹理 这里需要连接一个已加载或已创建的 RenderTexture 实例。 该端口没有”选择渲染纹理”按钮，请先使用以下方式获取 RenderTexture 实例： - 加载资产：把”类型”选为 RENDER_TEXTURE，从资产包按路径异步加载已有 .rt 文件。 - 获取资产：取出资产包里已加载的 RenderTexture。 - 新建渲染纹理：游戏运行时创建新实例，再用 初始化渲染纹理 初始化。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
window	渲染窗口	数据	reference / renderer.RenderWindow	渲染窗口（renderer.RenderWindow） RenderTexture 关联的渲染窗口实例，封装了宽高、相机绑定与调整大小接口。可连接到 渲染窗口节点 系列进一步使用。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

设置渲染纹理属性

一次性批量修改渲染纹理的常用配置字段，等同于部分覆盖 IRenderTextureCreateInfo 中的可写字段，再调用 reset(info) 完成更新。 公开引脚语义（重要）：除 exe 与 renderTexture 外，所有可写属性引脚默认不公开（isPublic: false），只有被显式公开的引脚才参与写入。若想保留目标属性原值不变，必须保持引脚不公开——仅断开连线不够，已公开的引脚会用内联控件默认值覆盖原值。 历史合并策略：游戏运行时会优先使用工作流缓存的 createInfo（如之前调用过 Initialize / Reset），做部分字段覆盖后再 reset；若无历史缓存（例如从外部加载的 .rt 资产），则退化到”当前可读字段 + 公开字段”合并方式，passInfo / externalFlag 等不可读字段将回退到引擎默认值。 建议：对从外部加载、且需要精确保留 passInfo / externalResLow / externalResHigh / externalFlag 原值的 RenderTexture，请优先使用 Initialize / Reset + 完整 IRenderTextureCreateInfo，而不是本节点。

节点信息

字段	值
节点 ID	renderTextureSetProperties
分类	资产
二级分类	图像
分组	RenderTexture
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
renderTexture	渲染纹理	数据	cc.Asset / RenderTexture	RenderTexture 渲染纹理 这里需要连接一个已加载或已创建的 RenderTexture 实例。 该端口没有”选择渲染纹理”按钮，请先使用以下方式获取 RenderTexture 实例： - 加载资产：把”类型”选为 RENDER_TEXTURE，从资产包按路径异步加载已有 .rt 文件。 - 获取资产：取出资产包里已加载的 RenderTexture。 - 新建渲染纹理：游戏运行时创建新实例，再用 初始化渲染纹理 初始化。	-	必填
name	名称	数据	string	名称（name） 渲染纹理的标识名称，用于调试与编辑器展示。默认不公开；公开后才参与写入。	输入框 默认值：""	可选 默认隐藏
width	宽度	数据	number	宽度（width） 渲染纹理的宽度（像素）。默认不公开；公开后才参与写入。	输入框 默认值：0	可选 默认隐藏
height	高度	数据	number	高度（height） 渲染纹理的高度（像素）。默认不公开；公开后才参与写入。	输入框 默认值：0	可选 默认隐藏
passInfo	渲染通道配置	数据	object	渲染通道配置（passInfo，gfx.RenderPassInfo） 指定颜色附件、深度/模板附件等渲染通道参数的对象。类型退化为 OBJECT（原始类型 gfx.RenderPassInfo 是 class，非 interface）。默认不公开；公开后才参与写入。 注意：对从外部加载的 .rt 资产，若不指定 passInfo，游戏运行时将回退到引擎默认值，可能与原始通道配置不同。	-	可选 默认隐藏
externalResLow	外部资产句柄低位	数据	number	外部资产句柄低位（externalResLow） 外部 GPU 纹理句柄的低 32 位。仅在需要绑定外部纹理（如 WebXR 等场景）时使用。默认不公开；公开后才参与写入。	输入框 默认值：0	可选 默认隐藏
externalResHigh	外部资产句柄高位	数据	number	外部资产句柄高位（externalResHigh） 外部 GPU 纹理句柄的高 32 位。仅在需要绑定外部纹理时使用。默认不公开；公开后才参与写入。	输入框 默认值：0	可选 默认隐藏
externalFlag	外部标志位	数据	number	外部标志位（externalFlag，gfx.TextureFlagBit） 外部纹理标志位（位标志组合值，退化为 NUMBER）。默认不公开；公开后才参与写入。	输入框 默认值：0	可选 默认隐藏

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
renderTexture	渲染纹理	数据	cc.Asset / RenderTexture	RenderTexture（透传） 把当前操作的 RenderTexture 实例原样传出，便于将多个配置节点串联在一起。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

新建渲染纹理

新建渲染纹理：在游戏运行时创建一个全新的空渲染纹理实例。 新建的实例尚未初始化，需要继续连接 初始化渲染纹理 节点并传入配置信息，才能指定宽高和渲染通道。 如果你只是需要加载已有的渲染纹理文件，请使用 加载资产 节点并把类型选为 RENDER_TEXTURE。

节点信息

字段	值
节点 ID	renderTextureCreate
分类	资产
二级分类	图像
分组	RenderTexture
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
renderTexture	渲染纹理	数据	cc.Asset / RenderTexture	RenderTexture 实例 新建的空渲染纹理实例。连接到 初始化渲染纹理 节点并传入 IRenderTextureCreateInfo 完成初始化。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

重置渲染纹理

重置 RenderTexture：调用 reset(info)，用新的 IRenderTextureCreateInfo 对已初始化的渲染纹理进行全量重新配置。 与 Initialize 不同，Reset 适用于已经使用过的 RenderTexture，会释放原有 GPU 资产后重新创建。常见场景：屏幕分辨率变化时更新渲染纹理尺寸。 如果只是简单调整尺寸，建议改用更轻量的 RenderTexture Resize。

节点信息

字段	值
节点 ID	renderTextureReset
分类	资产
二级分类	图像
分组	RenderTexture
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
renderTexture	渲染纹理	数据	cc.Asset / RenderTexture	RenderTexture 渲染纹理 这里需要连接一个已加载或已创建的 RenderTexture 实例。 该端口没有”选择渲染纹理”按钮，请先使用以下方式获取 RenderTexture 实例： - 加载资产：把”类型”选为 RENDER_TEXTURE，从资产包按路径异步加载已有 .rt 文件。 - 获取资产：取出资产包里已加载的 RenderTexture。 - 新建渲染纹理：游戏运行时创建新实例，再用 初始化渲染纹理 初始化。	-	必填
info	重置参数	数据	any	重置参数 用于重新配置渲染纹理的结构体，字段含义与 Initialize 相同。请先用 Make IRenderTextureCreateInfo 节点构造该结构体，再连接到此处。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
renderTexture	渲染纹理	数据	cc.Asset / RenderTexture	RenderTexture（透传） 把当前操作的 RenderTexture 实例原样传出，便于将多个配置节点串联在一起。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。