SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场render-textures

render-textures

编程与开发

查看项目

更新于 10-15 16:31

技能介绍

用途

本技能用于在 Phaser 4 中使用 RenderTexture 或 DynamicTexture，将游戏对象绘制到离屏纹理。适用于纹理合成、动态贴图、程序化生成、小地图、快照截图等场景。

主要能力

Phaser 4 将纹理绘制拆分为两层：

  • RenderTexture：一个可见的游戏对象，自带自动创建的 DynamicTexture，通过 this.add.renderTexture(x, y, w, h) 创建，继承自 Image，拥有位置、缩放、透明度等属性，属于单个 Scene。
  • DynamicTexture：Texture Manager 中的纹理，通过 this.textures.addDynamicTexture(key, w, h) 创建，本身不可见，必须赋给游戏对象，可按 key 共享，支持跨 Scene 使用。

选用建议：需要单一可见绘制表面（画布、拖尾、合成精灵）时用 RenderTexture；多个对象共享同一生成纹理、需要用于遮罩/着色器或跨 Scene 访问时用 DynamicTexture。

RenderTexture 是薄代理，draw()、stamp()、fill()、clear()、erase()、snapshot() 等方法都委托给底层的 DynamicTexture。注意 RenderTexture 继承 Image，原点默认 (0.5, 0.5)，如需左上角定位可调用 rt.setOrigin(0, 0)。

使用方式

命令缓冲（v4 架构）

在 Phaser 4 中，绘制调用（draw、stamp、fill、clear、erase、repeat、capture）不会立即执行，而是把命令推入 commandBuffer 数组，必须调用 .render() 刷新执行。

rt.clear();
rt.fill(0x000000);
rt.draw(sprite, 128, 128);
rt.render();  // 必需，否则不会显示

RenderTexture 的 renderMode 控制自动渲染：'render'（默认，手动调用 render()）、'redraw'（每帧自动 render() 但不显示自身）、'all'（每帧自动 render() 并显示自身）。可用 rt.setRenderMode('all') 设置。

默认 render() 后命令缓冲会清空，调用 preserve(true) 可在多次渲染间保留命令，使相同绘制每帧重放。

绘制方法

  • draw(entries, x?, y?, alpha?, tint?)：绘制游戏对象、纹理、Group、Container、Display List、其他 RenderTexture/DynamicTexture、Texture Frame、纹理 key 字符串或它们的数组。注意 alpha 和 tint 参数仅对 Texture Frame/字符串生效，游戏对象使用自身的 alpha 和 tint。
  • stamp(key, frame?, x?, y?, config?)：以完整变换控制绘制纹理帧，默认以 x/y 为中心（原点 0.5）。config 支持 alpha、tint、angle、rotation、scale、scaleX、scaleY、originX、originY、blendMode。
  • capture(entry, config)：以临时属性覆盖绘制游戏对象，之后恢复原值。config 支持 x、y、scale、alpha、rotation、transform（'local'、'world' 或 TransformMatrix）、camera 等。
  • fill(rgb, alpha?, x?, y?, w?, h?)：填充颜色，可指定区域。
  • clear(x?, y?, w?, h?)：清除为透明，可指定区域。
  • erase(entries, x?, y?)：使用 ERASE 混合模式在纹理上挖洞。
  • repeat(key, frame?, x?, y?, w?, h?, config?)：以平铺图案填充，config 支持 tileScaleX、tileScaleY、tilePositionX、alpha 等。
  • callback(fn)：在命令缓冲中插入回调，在 render() 期间执行。
  • resize(w, h?, forceEven?)：调整大小（会清除内容并重建帧缓冲）。
  • saveTexture(key)：在 Texture Manager 中注册，之后任何游戏对象都可用该 key。注意这是重命名而非复制，再次调用不同 key 会重命名；未保存就销毁 RenderTexture 会销毁纹理。

快照（像素捕获）

快照从帧缓冲读取像素，开销大且阻塞，应谨慎使用：

  • snapshot(callback, type?, quality?)：完整快照，回调收到 HTMLImageElement。
  • snapshotArea(x, y, w, h, callback, type?, quality?)：区域快照。
  • snapshotPixel(x, y, callback)：单像素，回调收到 Phaser.Display.Color，比完整快照便宜。

Stamp 游戏对象

this.add.stamp(x, y, texture, frame?) 创建一个轻量 Image 子类，渲染时忽略相机滚动和变换，内部被 DynamicTexture 用于绘制操作，也适合 HUD 元素。注意它与 stamp() 方法不同：rt.stamp(...) 是 RenderTexture/DynamicTexture 上的方法，this.add.stamp(...) 是创建 Stamp 游戏对象的工厂。

内部相机

RenderTexture 和 DynamicTexture 都有 .camera 属性，控制绘制游戏对象时的定位，可滚动、缩放、旋转。注意 stamp() 忽略相机，只有 draw() 和游戏对象渲染遵循它。

工厂方法

this.add.renderTexture(x, y, width?, height?)  // 默认 32x32
this.add.stamp(x, y, texture, frame?)
this.textures.addDynamicTexture(key, width?, height?, forceEven?)  // 默认 256x256

适用场景

  • 程序化生成：如用 DynamicTexture 生成星空背景，循环 stamp 星星并 render()。
  • 小地图：创建小尺寸 RenderTexture，setScrollFactor(0) 固定到相机，setRenderMode('all') 自动渲染，preserve(true)，在 update 中 clear、fill 并用 capture 绘制缩放后的世界对象。
  • 纹理合成与共享：用 saveTexture 或 DynamicTexture 的 key 让多个对象复用同一生成纹理。
  • 快照截图：将纹理内容导出为图像。

限制与注意事项

  • 必须调用 render()：Phaser 4 中绘制方法缓冲命令，未调用 render() 前不会显示（除非使用 renderMode 'all' 或 'redraw'）。
  • 不能绘制自身：DynamicTexture/RenderTexture 会静默跳过引用自身的条目。
  • render() 后命令缓冲清空：如需每帧重放相同命令，先调用 preserve(true)。
  • stamp() 忽略内部相机：只有通过 draw() 或 capture() 绘制的游戏对象遵循 .camera，纹理 stamp 按绝对位置定位。
  • 默认尺寸不同：RenderTexture 默认 32x32，DynamicTexture 默认 256x256。
  • forceEven 会向上取整：默认宽高会取整为偶数以保证渲染质量，需要精确奇数尺寸时传 false。
  • 快照开销大：使用 readPixels（WebGL）会阻塞 GPU 管线，避免逐帧快照。
  • WebGL1 帧缓冲无抗锯齿：绘制到 RenderTexture 的形状和 Graphics 可能有锯齿，建议使用预渲染精灵纹理。
  • resize() 会清除内容：调整大小会销毁并重建帧缓冲。
  • saveTexture 是重命名而非复制。
  • draw() 的 alpha/tint 参数仅影响 Texture Frame。
  • WebGL 上下文丢失：DynamicTexture 内容会丢失，需监听 restorewebgl 事件重绘。
  • Group/Container 的 x、y 偏移是叠加的：用 rt.draw(group, x, y) 时偏移会加到每个子对象位置上。

源码文件映射

  • src/gameobjects/rendertexture/RenderTexture.js：RenderTexture 游戏对象（继承 Image，代理到 DynamicTexture）
  • src/gameobjects/rendertexture/RenderTextureFactory.js：this.add.renderTexture() 工厂注册
  • src/gameobjects/rendertexture/RenderTextureRender.js：RenderTexture 的 WebGL/Canvas 渲染函数
  • src/gameobjects/rendertexture/RenderTextureRenderModes.js：枚举 RENDER、REDRAW、ALL
  • src/textures/DynamicTexture.js：核心 DynamicTexture 类（命令缓冲、绘制、快照）
  • src/textures/DynamicTextureCommands.js：命令常量（CLEAR、FILL、STAMP、DRAW、ERASE 等）
  • src/textures/typedefs/StampConfig.js：stamp() 的 StampConfig 类型定义
  • src/textures/typedefs/CaptureConfig.js：capture() 的 CaptureConfig 类型定义
  • src/gameobjects/stamp/Stamp.js：Stamp 游戏对象（轻量 Image，忽略相机滚动）
  • src/gameobjects/stamp/StampFactory.js：this.add.stamp() 工厂注册

相关技能：../sprites-and-images/SKILL.md、../loading-assets/SKILL.md、../cameras/SKILL.md