# 图形渲染模块 **脚本入口：** `eve.Graphics()` 清屏、2D 图元、纹理、Canvas、摄像机和 3D 渲染。Camera2D/Camera3D 提供屏幕与世界坐标换算，供 2D/3D 拾取使用；形状命中测试见 [Math](math.md)，物理体查询见 [Physics](physics.md)。 ## 基本用法 ```squirrel gfx.setBackgroundColor(0.08, 0.1, 0.16, 1.0); gfx.clear(); gfx.drawSolidRect(40, 40, 160, 80, 0.2, 0.7, 1.0, 1.0); ``` ## 对象关系与调用时机 `Graphics` 管理设备、swapchain、camera、light 和提交；Texture/Shader/Mesh/Renderable 是资源或场景对象。CPU 资源创建在 init，帧内只更新参数并 draw。 ## 目标导向指南 ### 绘制 2D 游戏帧 在 `eve_render()` 开始调用 `clear()`，随后按背景、地图、角色、粒子、UI 的顺序提交。纯色占位使用 `drawSolidRect()`；已有 Texture 使用 `drawTexturedRect()`。需要围绕矩形中心旋转的精灵可调用 `drawTexturedRectRotated(texture, centerX, centerY, width, height, degrees, r, g, b, a)`；屏幕坐标 Y 轴向下，因此正角度表现为顺时针旋转。正常主循环由引擎负责 present。 `drawText(font, text, x, y, r, g, b, a, scale)` 在当前屏幕或 Canvas 坐标的任意 位置绘制 UTF-8 文本，`(x, y)` 是该行左上角。`font` 必须是 `newFont()` 返回的字体； 绘制调用不读取或修改当前字体状态。原有的 `print(text, x, y, r, g, b, a, scale)` 继续保留，并使用 `setFont()` 选择的当前字体。 需要 UV 动画、旋转、独立混合模式或程序化变换时，使用脚本精灵对象： ```squirrel local sprite = gfx.newSprite2D(); sprite.setTexture(sheet.getTexture()); sprite.setQuad(quad); sprite.setPosition(400, 270); sprite.setScale(2.0, 2.0); sprite.setRotation(30.0); // degree, rotate around rect center sprite.setAnchor(0.25, 0.75); // normalized rotation pivot sprite.setFlip(true, false); // mirror UV without negative scale sprite.setBlend("alpha"); // alpha | premultiplied | additive | multiply // eve_render: clear/draw background first, then submit all live Sprite2D objects gfx.renderSprites(); ``` `Sprite2D` 还提供 size、color、layer、visible、receiveLight、castOcclusion 等属性。 裁边动画通常由 `SpriteAnim.bindSprite(sprite)` 自动调用 `setFrameLayout`，无需游戏代码逐帧修正偏移。 不再使用时调用 `destroy()`；`renderSprites()` 是聚合提交接口，不要再把同一精灵加入另一条 2D 队列，以免重复绘制。 ### 渲染带光照的 3D 对象 初始化时创建 mesh、shader 和 renderable，设置 camera、ambient 和 directional light；每帧只更新 transform/material 参数，最后调用 `render3D()`。阴影开关、bias 和 strength 应逐场景调节。 `Camera3D` 默认使用透视投影。等距视图可调用 `setOrthographic(height)`，其中 `height` 是世界空间中的垂直可视范围；`setPerspective()` 恢复透视投影。 `setClipPlanes(near, far)` 配置两种投影共用的近、远裁剪面，并要求 `0 < near < far`。 ### 实时编辑与替换 Shader 开发工具可保留已有 `Shader` 对象及其材质引用，仅替换内部后端资源： ```squirrel local result = gfx.replaceShaderFromGlsl(shader, vertexSource, fragmentSource); // WebGPU 后端使用：gfx.replaceShaderFromWgsl(shader, vertexSource, fragmentSource) if (!result.ok) { print(result.diagnostics); } ``` 两个接口都返回统一的结构化 `Result`，调用方必须检查 `ok` 或显式忽略结果。编译或 管线创建失败时，原 `Shader` facade、已声明 uniform 以及上一份可用管线保持不变， 因此编辑器可继续显示最后一次成功的效果。空的 vertex source 表示沿用引擎默认顶点 阶段；调用必须发生在 Graphics 所属的渲染线程。GLSL 是 Vulkan 开发路径，WGSL 是 WebGPU 开发路径；当前后端不支持对应源码格式时会返回 `Unsupported` 和诊断信息。 ### 纹理过滤（mipmap / 各向异性 / LOD） 默认 `newTexture` 仍为线性过滤、单级 mip（兼容旧行为）。需要三线性与各向异性时： ```squirrel // generateMipmaps=true, maxAnisotropy=16, filter/mipmap="linear", lodBias=0 tex <- gfx.newTextureWithSampler(img, false, false, true, 16.0, "linear", "linear", 0.0); print(tex.getMipmapCount()); gfx.setTextureSampler(tex, "nearest", "none", 1.0, 0.0); // 像素风 print(gfx.getMaxAnisotropy()); ``` C++ 侧使用 `TextureCreateInfo::withMipmaps()` / `TextureSampler::anisotropic()`，并通过同名 `setTextureSampler` 重载热更新采样状态（字符串版参数与脚本一致）。`filter` 只接受 `nearest`/`linear`，`mipmap` 只接受 `none`/`nearest`/`linear`，传错会抛异常而不是静默回退。Cubemap（IBL）默认生成完整 mip 链，供 `textureLod` 按粗糙度采样。 几何 LOD：`Renderable3D.setMeshLod(index, mesh, switchDistance)`，`RenderSystem3D` 按相机距离选择网格。 需要把运行对象交给 Editor/MCP 等跨帧工具时，同时读取 `Renderable3D.getEntityId()` 与 `getEntityGeneration()`；两者共同构成临时 ECS handle， generation 用于拒绝实体销毁后被复用的旧 id。不要只长期保存 entity id。 Agent 完成材质事务后，可用 `getTintR()`、`getTintG()`、`getTintB()` 与 `getRoughness()` 独立核对字段材质的运行时状态。 ### 材质（Material）与模型部件 把着色方法（`pbr` / `unlit` / `hair` / `custom`）、贴图和 PBR 参数打成一个 `Material`，挂到整模或某个部件： ```squirrel local mat = gfx.newMaterial(); mat.setShadingModel("pbr"); mat.setAlbedoTexture(albedo); mat.setNormalTexture(nrm); mat.setSurfaceMode("transparent"); // opaque | masked | transparent mat.setBlendMode("alpha"); // alpha | premultiplied | additive | multiply mat.setDepthWrite(false); mat.setDoubleSided(true); mat.setSortPriority(0); // 同优先级按相机深度从后向前排序 mat.setMetallic(0.2); mat.setRoughness(0.5); local r = Renderable3D.create(); r.setMaterial(mat); // 整模 // 或多部件：r.setPart(0, "body", bodyMesh, bodyMat); r.setPartSortPriority(0, 100); // 每实例覆盖透明排序，不修改共享 Material r.clearPartSortPriority(0); // 恢复使用 Material.getSortPriority() local effectiveOrder = r.getPartSortPriority(0); ``` 遮罩材质使用 `setSurfaceMode("masked")`、`setAlphaCutoff()` 和 `setAlphaTechnique("cutoff" | "dither" | "coverage")`。对应查询接口为 `getSurfaceMode()`、`getBlendMode()`、`getDepthWrite()`、`getDoubleSided()`、 `getSortPriority()`、`getAlphaCutoff()` 和 `getAlphaTechnique()`。纹理 Alpha 数据可用 `Texture.setAlphaConvention("straight" | "premultiplied")` 声明，并通过 `Texture.getAlphaConvention()` 查询。 虚拟纹理材质通过 `setVirtualTexture(albedoAtlas, normalAtlas, pageTable, pageCountX, pageCountY, borderFraction)` 显式启用 atlas/page-table 路径； `usesVirtualTexture()` 可查询当前模式，`clearVirtualTexture()` 恢复传统材质贴图路径。 三个纹理对象必须至少存活到材质停止使用它们为止； 参数校验失败时 `setVirtualTexture()` 会抛出包含诊断信息的脚本异常。 ### 高级渲染与屏幕空间效果 GBuffer、毛发、体积光、AO、GI 与抗锯齿集中在 [高级渲染与屏幕空间效果](graphics/rendering-effects.md)，避免各类渲染特性持续修改本概览。 ### 2D 屏幕拾取 `Camera2D` 用 `setPosition` / `setZoom` 控制视口中心与缩放；`screenToWorldX/Y(screenX, screenY, viewW, viewH)` 把鼠标像素换成世界坐标（`viewW/H` 通常取 `gfx.getWidth/Height`），再交给 Math 的 `pointIn*` 或 Physics 的 `testPoint` / `queryAABB`。 ### 3D 屏幕拾取 `Camera3D.screenToRay(screenX, screenY, viewW, viewH)` 写入眼点与单位方向，用 `getScreenRayOrigin*` / `getScreenRayDir*` 读取，再对包围球/盒调用 Math 的 `raycastSphere` / `raycastBox`。 ### 曲面瀑布 `Waterfall.createCurvedSheet(width, height, segX, segY, curveDepth, lipOverhang)` 创建带横向弧度和顶部探出段的细分瀑布网格，适合贴合崖壁并形成自然的离壁水帘；原有 `createSheet(width, height)` 仍用于平面瀑布。 ```squirrel local fall = gfx.newWaterfall(); fall.createCurvedSheet(3.0, 7.0, 28, 48, 0.75, 0.85); ``` ## 常见问题 - 忘记每帧 `clear()`，保留未定义的旧帧内容。 - 每帧编译 shader 或上传纹理。 - 2D/UI/3D 提交顺序错误导致覆盖。 - 拾取时 `viewW/H` 与实际渲染 drawable 不一致，射线会偏。 ## Agent 运行时观察 `eve_renderable3d_get` 使用完整 ECS `entityId` + `generation` 读取 live Renderable3D 的 transform、 field-backed PBR 参数与资源占用标志；陈旧 identity 返回结构化 `stale`。 `eve_editor_execute_observe` 的默认 `renderable3d` observer 在写入前验证同一 identity，再通过 Editor 事务修改目标，并在一个响应中返回 live `before/after`、事务回执和 Editor snapshot。传入 `expect` JSON 子集和可选 `tolerance` 后，引擎还会返回 `converged`、`maxError` 与不匹配字段路径， Agent 可直接决定是否继续纠正；无效期望会在写入前拒绝。同一协议还支持 `scene-node` observer， 因此 Agent 不必为场景和渲染对象维护两套调用编排。 ## API 快查 `drawScene3DRGBA(x, y, w, h, r, g, b, a)` 把最近一次 `render3D()` 产生的正式 场景颜色复合到当前目标（交换链或 `Canvas`）。它适合自定义编辑器把与游戏相同的场景 呈现在任意 Viewport 中；与 `renderScene3DToCanvas` 的独立预览渲染不同，它复用完整 运行时场景管线。 `updateTextureFromImageData(texture, imageData)` 将尺寸相同的 RGBA8 `ImageData` 重新上传到由当前 Graphics 后端创建的已有纹理；纹理对象保持不变，可继续被材质引用。 该方法必须在渲染线程调用，后端所有权、格式或尺寸不匹配时抛出异常。 C++ 渲染适配器可调用 `updateTextureRegion(texture,x,y,width,height,rgba,bytesPerRow)` 更新单 mip RGBA8 纹理的子矩形。Vulkan 使用 staging buffer 和原图 `copyBufferToImage`， WebGPU 使用带 origin 的 `WriteTexture`；两者都不重建 Texture、采样器或描述符。 多个离散矩形应使用 `updateTextureRegions(texture, regions)`：它在任何写入前验证整个 批次；Vulkan 将所有 region 紧密打包进一个 staging buffer 并只提交一次。 下列方法名来自当前 Squirrel 绑定；同一模块创建的辅助对象（例如 `World`、`Body`、`Source`）的方法也列在这里。 - `bakeMeshMorph()`、`newMeshFromArrays()`、`updateMeshVertices()`、`clear()`、`clearMorphWeights()`、`declareFloat()`、`declareMatrix()`、`declareVec2()`、`declareVec3()`、`declareVec4()` - `drawSolidRect()`、`drawTexturedRect()`、`drawTexturedRectRotated()`、`drawOcclusionSolid()`、`drawOcclusionTexture()`、`getCastShadow()`、`getCastOcclusion()`、`getDirX()`、`getDirY()`、`getDirZ()`、`getHeight()`、`getMorphCount()` - `getMorphName()`、`getMorphWeight()`、`getName()`、`getRadius()`、`getScreenRayDirX()`、`getScreenRayDirY()`、`getScreenRayDirZ()`、`getScreenRayOriginX()` - `getScreenRayOriginY()`、`getScreenRayOriginZ()`、`getShader()`、`getShadowBias()`、`getShadowStrength()`、`getType()`、`getUniformIndex()`、`getVertexCount()`、`getIndexCount()` - `getVolumetric()`、`getVolumetricIntensity()`、`getWidth()`、`getX()`、`getY()`、`getYaw()`、`getZ()`、`getZoom()`、`hasMorph()`、`hasMorphData()` - `hasUniform()`、`isEnabled()`、`isMorphDirty()`、`newHairShader()`、`newMeshCylinder()`、`newMeshShader()`、`newMeshShaderVF()`、`newMeshSphere()`、`newQuad()`、`newShader()` - `newShaderFromSpvFile()`、`replaceShaderFromGlsl()`、`replaceShaderFromWgsl()`、`newTexture()`、`newTextureWithSampler()`、`updateTextureFromImageData()`、`setTextureSampler()`、`getMaxAnisotropy()`、`newVolumetric()`、`newAmbientOcclusion()`、`newGlobalIllumination()`、`newAntiAliasing()`、`setMsaaSamples()`、`getMsaaSamples()`、`present()`、`render3D()`、`reset()`、`screenToRay()`、`screenToWorldX()`、`screenToWorldY()` - `sendFloat()`、`sendVec2()`、`sendVec3()`、`sendVec4()`、`setActive()`、`setAmbient()`、`setBackgroundColor()`、`setCamera()` - `setCanvas()`、`setCastOcclusion()`、`setCastShadow()`、`setCloudShadows()`、`setColor()`、`setDirection()`、`setDirectionalLight()`、`setEnabled()`、`setEnvIntensity()`、`setEnvMap()` - `setEye()`、`setFov()`、`setMesh()`、`getMesh()`、`setMeshLod()`、`clearMeshLod()`、`getMeshLodCount()`、`getMeshLodLevelAtDistance()`、`setMetallic()`、`setMorphWeight()`、`setNormalTexture()`、`setHeightTexture()`、`setPosition()`、`setRadius()` - `setReceiveLight()`、`setReceiveShadow()`、`setRotation()`、`setRoughness()`、`setScale()`、`setShader()`、`setHair()`、`getHair()`、`setShadowBias()`、`setShadowStrength()` - `setTarget()`、`setTexCellBomb()`、`getTexCellBombScale()`、`getTexCellBombStrength()`、`getTexCellBombRotation()`、`setParallax()`、`getParallaxScale()`、`getParallaxMinLayers()`、`getParallaxMaxLayers()`、`setTexture()`、`setTint()`、`setType()`、`setUp()`、`setViewport()`、`setVisible()`、`setVolumetric()`、`setVolumetricIntensity()`、`setYaw()` - `setZoom()`、`worldToScreenX()`、`worldToScreenY()`、`Texture.getMipmapCount()` - 字体：`newFont()`、`setFont()`、`getFont()`、`drawText()`、`print()`、`getAscent()`、`getBaseline()`、`hasGlyph()` - `AlphaMask`：`newAlphaMask()`、`setThreshold()`、`getThreshold()`、`setSoftness()`、`getSoftness()`、`setInverted()`、`getInverted()` - `Sprite2D`：`setPosition()`、`getX()`、`getY()`、`setRotation()`、`getRotation()`、`setScale()`、`getScaleX()`、`getScaleY()`、`setSize()`、`getWidth()`、`getHeight()`、`setTexture()`、`getTexture()`、`setQuad()`、`getQuad()`、`setColor()`、`setLayer()`、`getLayer()`、`setVisible()`、`getVisible()`、`setReceiveLight()`、`getReceiveLight()`、`setBlend()`、`getBlend()`、`setAnchor()`、`getAnchorX()`、`getAnchorY()`、`setFlip()`、`getFlipX()`、`getFlipY()`、`setFrameLayout()`、`setCastOcclusion()`、`getCastOcclusion()`、`destroy()` - `Volumetric`：`setQuality`、`setMode`、`scatter`、`applyFromScene`、`rayMarch`、`applyFog`、`setFogHeight`、`setFogStart`、`setFogEnd`、`setCamera`、`setLightDirection`、`setDensity` 等 - `FogVolume`：`setShape/getShape`、`setPosition`、`setSize`、`setExtinction/getExtinction`、`setAlbedo`、`setEmissive`、`setAnisotropy/getAnisotropy`、`setEdgeFalloff/getEdgeFalloff`；调用 `Volumetric.setCamera()` 后，通过 `injectFroxelLocalVolume(volume)` 按当前视锥注入 froxel 网格。 - `Volumetric` froxel：`configureFroxelGrid`、`clearFroxelGrid`、 `injectFroxelHeightFog`、`integrateFroxel`、`uploadFroxel`、 `applyFroxel`、`applyFroxelTo` - `AmbientOcclusion`：`setQuality`、`setMode`、`setCamera`、`setRadius`、`setBias`、`setIntensity`、`setPower`、`compute`、`blur`、`applyOverlay`、`applyFromDepth`、`resolutionFor` 等 - `GlobalIllumination`：`setQuality`、`setCamera`、`setRadius`、`setIntensity`、`setLightDirection`、`setLightColor`、`applyFromDepth`、`getSampleCount` 等 - `AntiAliasing`：`setQuality`、`setMode`、`apply`、`applyTo`、`applyCanvas`、`applyCanvasTo`、`suggestScale`、`resolutionFor`、`setFloat`、`getFloat` 等 ## 使用要点 - 模块对象和它创建的资源对象应保存在全局或实体状态中，不要在每帧重复创建。 - 带 `update(dt)` 的系统应在 `eve_update` 调用；绘制方法应在 `eve_render` 调用。 - 参数约束、默认值和返回类型以对应模块头文件及 `addFunc` 绑定为准；本文 API 快查与当前源码同步生成。 **源码：** [`src/modules/graphics/`](../../../src/modules/graphics/) **相关测试：** 在 [`test/`](../../../test/) 中搜索 `graphics`、`Camera2D`、`Camera3D`。 ### HDR 与反射探针绑定 下列绑定用于 HDR 图像、反射探针采集/注册、天空环境、曝光、Bloom 与反射链质量控制： `applyConfiguredToCamera`、`applyToCamera`、`clearReflectionProbe`、`configureInfluence`、`filterAndPublish`、`getActiveCubemap`、`getAdaptiveFaceBudget`、`getAdaptiveFilterSamples`、`getBloomIntensity`、`getBloomThreshold`、`getCaptureClusteredLighting`、`getCaptureFarDistance`、`getCaptureLodDistanceScale`、`getCaptureMask`、`getCaptureTransparent`、`getCenterX`、`getCenterY`、`getCenterZ`、`getCount`、`getEnvProbeCenterX`、`getEnvProbeCenterY`、`getEnvProbeCenterZ`、`getEnvProbeExtentX`、`getEnvProbeExtentY`、`getEnvProbeExtentZ`、`getEnvironmentLighting`、`getEnvironmentLightingIntensity`、`getExposure`、`getFaceCanvas`、`getGpuBudgetMs`、`getInfluenceBlendDistance`、`getInfluenceExtentX`、`getInfluenceExtentY`、`getInfluenceExtentZ`、`getInfluenceIntensity`、`getInfluencePriority`、`getLastCandidateCount`、`getLastCapturedFaceCount`、`getLastFilterSampleCount`、`getLastPublishedCount`、`getLastSelectedCount`、`getMaxRoughness`、`getPendingFaceCount`、`getPostProcessQuality`、`getPublishedRevision`、`getReflectionCaptureEnabled`、`getReflectionCaptureMask`、`getReflectionProbeCount`、`getReflectionQuality`、`getRefreshInterval`、`getResolution`、`getResolutionScale`、`getRevision`、`getSelectionHysteresis`、`getSkyB`、`getSkyFaceColor`、`getSkyFaceTexture`、`getSkyFaceTextureScale`、`getSkyG`、`getSkyIntensity`、`getSkyR`、`getSmoothedGpuDurationMs`、`getStagedRevision`、`getStagingCubemap`、`getThickness`、`getTotalCapturedFaceCount`、`getUpdateMode`、`hasEnvProbe`、`isAutoExposure`、`isCaptureComplete`、`isCapturePending`、`isRecaptureQueued`、`newHDRImageData`、`newReflectionProbeCapture`、`newReflectionProbeRegistry`、`queueCapture`、`queueCaptureAABB`、`remove`、`reportGpuDurationMs`、`requestCapture`、`setAutoExposure`、`setBloom`、`setCaptureClusteredLighting`、`setCaptureLodDistanceScale`、`setCaptureMask`、`setCaptureTransparent`、`setEnvironmentLighting`、`setExposure`、`setGpuBudgetMs`、`setMaxRoughness`、`setReflectionCaptureEnabled`、`setReflectionCaptureMask`、`setReflectionProbe`、`setReflectionQuality`、`setRefreshInterval`、`setResolutionScale`、`setSelectionHysteresis`、`setSkyColor`、`setSkyFaceColor`、`setSkyFaceTexture`、`setSkyFaceTextureScale`、`setUpdateMode`、`stageCapturedFaces`、`tick`、`tickAdaptive`、`updateCamera`。