企业官网建设流程全解析

• 文档
• 教程
• 游戏开发

导读

DPITexture是 Godot 引擎提供的一种基于 SVG 源数据、可随视口缩放自动重新光栅化的Texture2D子类，专为 UI 图标、主题纹理等需要在任意分辨率下保持清晰的场景设计。本文以 Godot 官方文档 classes/class_dpitexture.rst 为主线，结合仓库中的导入管线与多分辨率渲染教程，完整讲解其属性、方法、导入配置方式与底层 oversampling（过采样）原理，帮助你在项目中实现「字体与图像双重高清」的跨分辨率方案。

DPITexture 是什么：可自动缩放的 SVG 纹理

DPITexture在 Godot 类继承体系中位于：

Object < RefCounted < Resource < Texture < Texture2D < DPITexture

官方文档 class_dpitexture.rst 明确说明，它是一种基于 SVG 图像、可自动缩放的Texture2D。与普通位图纹理不同，DPITexture保存的是SVG 矢量源数据而非像素，因此可以在运行时按需重新光栅化，以匹配视口缩放系数（viewport scale）与字体过采样（font oversampling），从而避免 UI 图标在放大显示时出现模糊或锯齿。

需要特别注意的是，官方文档将其标记为Experimental（实验性）——这意味着该类的 API 在未来的 Godot 版本中可能被修改或移除，生产项目接入时需评估风险。

适用场景速览：编辑器/插件图标、自定义类图标、UI 主题中的小图标、准星等可能被运行时改变 Scale 的控件元素，以及高分辨率下需要保持锐利的任何 2D 矢量纹理。

核心原理：重光栅化与 oversampling 链路

DPITexture的价值不在于「矢量本身可无限缩放」，而在于它与 Godot 的 oversampling 系统深度联动。文档描述中指出：

DPITextures are used to automatically re-rasterize icons and other texture based UI theme elements to match viewport scale and font oversampling.

也就是当视口缩放因子变化时，纹理会从矢量源重新渲染，保证像素密度始终匹配显示需求。这一行为受以下机制协同驱动：

• Project Settings > display/window/stretch/mode：当设为"canvas_items"模式时，画布内容会按缩放比例整体重绘，DPITexture在此模式下会自动跟随视口缩放重新光栅化；
• Viewport.oversampling_override（class_viewport.rst 中的oversampling/oversampling_override属性）：oversampling_override默认为0.0，若大于零则作为字体过采样因子使用，否则过采样值等于视口缩放；
• Viewport.oversampling（默认true）：该属性决定是否在满足条件时启用字体与DPITexture过采样。

从仓库的多分辨率教程 tutorials/rendering/multiple_resolutions.rst 可以看到完整的产品级设定：

一个关键事实：只有 SVG 是唯一能以DPITexture形式导入的图像格式（见 importing_images.rst），因为其他格式存储的是位图数据而非矢量，无法支持重新光栅化。

属性详解：6 个可调参数

DPITexture暴露了 6 个属性（含 1 个继承重写），下面逐一说明语义与默认值。

base_scale（默认1.0）

set_base_scale(value: float) get_base_scale() -> float

纹理缩放因子。1.0表示使用 SVG 的原始尺寸，数值越大图像越大。注意它与字体过采样不同：它直接影响 SVG 在 2D 中的物理显示尺寸（对应 Import dock 中的SVG > Scale选项，该选项仅对 SVG 图片可用）。配合saturation与color_map的默认值1.0/{}，可作为导入管线中的统一缩放入口。

color_map（默认{}）

set_color_map(value: Dictionary) get_color_map() -> Dictionary

颜色重映射表。文档描述为「If set, remaps texture colors according to Color-Color map」，即按Color→Color的键值映射关系替换纹理颜色。常用于主题化换肤（例如将同一图标渲染为深色主题/浅色主题配色），是实现「一套 SVG、多套配色」的轻量手段。

fix_alpha_border（默认false）

set_fix_alpha_border(value: bool) get_fix_alpha_border() -> bool

半透明边缘修复开关。设为true时，会在从透明过渡到不透明的区域填充与周围相同的颜色像素。对于使用双线性过滤（bilinear filtering）显示的纹理，这有助于消除从图像编辑软件导出图片时产生的描边/黑边效果。

premult_alpha（默认false）

set_premult_alpha(value: bool) get_premult_alpha() -> bool

预乘 alpha 转换开关。这是修复暗色描边的另一种方案（与fix_alpha_border互为替代）。开启后纹理会被转换为预乘 alpha 格式，但预乘 alpha 纹理必须搭配特定材质才能正确显示，详见下文专节。

saturation（默认1.0）

set_saturation(value: float) get_saturation() -> float

饱和度覆盖值，1.0表示保持原始饱和度，用于统一调整一组图标的视觉浓淡。

resource_local_to_scene（重写自 Resource，默认false）

该属性由基类Resource提供，DPITexture将其默认值固定为false（覆盖Resource的默认行为）。启用后资源会随场景实例化产生独立副本，适合在场景间隔离运行时修改（如动态改色）的场景。

premult_alpha：2D 与 3D 的正确显示姿势

官方文档特别强调：启用premult_alpha后，纹理被转换为预乘 alpha 格式，必须配合特定的混合模式材质，否则渲染结果会不正确。

2D 场景：

• 在CanvasItem上创建CanvasItemMaterial，并将其混合模式设置为CanvasItemMaterial.BLEND_MODE_PREMULT_ALPHA；
• 若使用自定义canvas_itemshader，则需要在 shader 中声明render_mode blend_premul_alpha;。

3D 场景：

• 为使用该纹理的材质创建BaseMaterial3D，并将混合模式设置为BaseMaterial3D.BLEND_MODE_PREMULT_ALPHA；
• 若使用自定义spatialshader，同样需要render_mode blend_premul_alpha;。

# 2D 示例：为使用预乘 alpha 纹理的 Sprite2D 配置材质 var mat = CanvasItemMaterial.new() mat.blend_mode = CanvasItemMaterial.BLEND_MODE_PREMULT_ALPHA $Sprite2D.material = mat

选择fix_alpha_border还是premult_alpha，取决于素材来源与渲染管线：前者零成本接入常规纹理，后者需要为显示节点配置专用材质，但在边缘质量上通常更优。

方法详解：5 个核心 API

静态方法 create_from_string（运行时构造入口）

static DPITexture create_from_string(source: String, scale: float = 1.0, saturation: float = 1.0, color_map: Dictionary = {})

静态方法，无需实例即可调用。它分配并设置source为 SVG 数据，同时一次性完成scale、saturation、color_map的初始化。这是纯运行时创建DPITexture的主要途径，适合动态生成图标（例如从网络/数据库读取 SVG 字符串的场景）。

# 运行时从 SVG 字符串创建 DPITexture var svg_source = '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64">' + \ '<rect width="64" height="64" fill="#e74c3c"/></svg>' var tex = DPITexture.create_from_string(svg_source, 1.0, 1.0, {})

set_source / get_source

set_source(source: String) get_source() -> String

设置/获取该纹理的 SVG 源码字符串。set_source相当于替换矢量源数据（之后纹理可在下一次光栅化时反映新内容），get_source用于取回当前 SVG 源码，便于序列化、对比或克隆。

get_scaled_rid（过采样光栅化核心）

RID get_scaled_rid() const

返回为匹配当前正在绘制的 canvas item 的过采样系数而重新光栅化后的纹理RID。这是DPITexture在渲染管线中的关键调用点：Godot 在绘制时通过它获取与当前缩放匹配的纹理资源，从而实现「边绘制边按需重光栅化」。该方法是 const（无副作用，不修改成员变量）。

set_size_override

set_size_override(size: Vector2i)

将纹理强制调整为指定像素尺寸。当需要固定输出大小（例如适配固定尺寸的 UI 槽位）时使用。

实战接入：从导入配置到运行时代码

方式一：编辑器导入（推荐，静态资源）

在 FileSystem dock 中选中 SVG 文件，在 Import dock 中将导入类型从默认的Texture2D改为DPITexture（只有 SVG 图片会出现该选项，详见 importing_images.rst）。

与 SVG 导入相关的专属配置项包括：

配套的导入器是ResourceImporterSVG（class_resourceimportersvg.rst），它的职责即「Imports an SVG file as an automatically scalable texture」并导入DPITexture资源，其属性（base_scale、color_map、fix_alpha_border、premult_alpha、saturation以及独有的compress，默认true）与DPITexture的属性一一对应，构成「导入参数 → 运行时属性」的完整链路。

方式二：运行时创建（动态素材）

调用DPITexture.create_from_string(...)直接构造实例，配合TextureRect/Sprite2D等节点使用：

var tex = DPITexture.create_from_string(svg_source) $TextureRect.texture = tex # 后续可按需调整 tex.set_base_scale(2.0) tex.set_saturation(0.8) tex.set_color_map({ Color(1, 0, 0): Color(0, 0, 1) }) tex.set_size_override(Vector2i(128, 128))

与过采样联动的完整链路

1. 项目启用display/window/stretch/mode = "canvas_items"，让画布内容随视口缩放；
2. 将需要高清显示的 SVG 导入为DPITexture；
3. 运行时若节点自身的Scale会变化（如准星、动态 UI 元素），可将其 Inspector 中的Oversampling with Scale设为Enabled——此时纹理会按节点缩放重新光栅化。注意：非均匀缩放虽可用，但过采样始终均匀应用，较短的轴可能出现锯齿；且若缩放频繁变化，CPU 负担会明显上升，因为每次都需要重新渲染纹理；
4. 特殊场景下可用Viewport.oversampling_override（大于 0 时作为过采样因子，否则等于视口缩放）强制指定过采样强度；
5. 在 2D 编辑器中可通过View > Auto Resample CanvasItems开关实时预览不同缩放系数下的光栅化效果。

已知限制与注意事项

• SVG 渲染依赖 ThorVG 库：Godot 的 SVG 渲染由 ThorVG 提供（见 importing_images.rst），其对 SVG 特性的支持有限，复杂矢量可能渲染不正确；
• SVG 内的文本不会自动光栅化：由于所用 SVG 库不支持文本栅格化，必须先通过 Inkscape 等工具将文本转为路径，否则文本不会出现在栅格化图像中（例如使用inkscape --export-text-to-path --export-filename out.svg in.svg）；
• 只有 SVG 支持此方案：位图格式（PNG、WebP 等）无法享受图像过采样，需依赖 mipmap 等其他手段缓解缩小采样时的锯齿；
• 实验性 API：类可能在未来版本变更或移除，请关注引擎版本升级公告。

小结

DPITexture是 Godot 面向高分辨率 UI 提供的「矢量 + 过采样」组合拳的核心：它以 SVG 为源，在视口缩放、节点缩放、字体过采样等多条触发链路上按需重光栅化，让图标与主题纹理在任意分辨率下保持像素级锐利。配合 importing_images.rst 的导入管线、multiple_resolutions.rst 的多分辨率策略，以及 class_viewport.rst 中oversampling/oversampling_override的视口级控制，即可构建一套完整、可控、可预览的跨分辨率 UI 图像方案。

• 文档
• 教程
• 游戏开发