Godot 可视化着色器 Cubemap 参数节点 VisualShaderNodeCubemapParameter 完全指南

• 文档
• 教程
• 游戏开发

【免费下载链接】godot-docs

Godot Engine official documentation

项目地址：https://gitcode.com/GitHub_Trending/go/godot-docs

点击查看免费下载

导读

VisualShaderNodeCubemapParameter 是 Godot Engine 可视化着色器（VisualShader）图形节点体系中用于声明立方体贴图（Cubemap）着色器参数的核心节点：它在着色器语言层面被翻译为uniform samplerCube声明，其输出端口可以直接接入VisualShaderNodeCubemap采样节点，从而在 3D 材质中实现天空盒反射、环境采样等效果。读完本文，你将掌握该节点的类层次定位、底层 GLSL 对应关系、在可视化着色器编辑器中的完整接入流程，以及与之配套的 Cubemap 资源导入与采样属性调优方法。

一、节点定位：类继承关系与作用

在 Godot 文档仓库中，该节点由 class_visualshadernodecubemapparameter.rst 记录，官方定义其为"可在可视化着色器图中使用的 Cubemap 参数节点"（ACubemapparameter node to be used within the visual shader graph）。

它的完整继承链为：

VisualShaderNodeCubemapParameter < VisualShaderNodeTextureParameter < VisualShaderNodeParameter < VisualShaderNode < Resource < RefCounted < Object

这串继承关系说明了三层含义：

1. 它是一类着色器节点（VisualShaderNode）：与所有可视化着色器节点一样，它是Resource派生资源，可被保存在可视化着色器图内。
2. 它是"参数节点"（VisualShaderNodeParameter）：参数节点的本质是"声明一个由外部设置的着色器变量"——在 class_visualshadernodeparameter.rst 中明确说明，参数在ShaderMaterial中被暴露为属性，既可以在检查器（Inspector）中赋值，也可以从脚本写入。
3. 它是"纹理参数节点"（VisualShaderNodeTextureParameter）：它继承了纹理采样相关的一组属性（过滤、重复、类型、默认颜色），详见本文第五节。官方文档还列出了VisualShaderNodeCubemapParameter是该基类的重要子类之一，同族的还有VisualShaderNodeTexture2DArrayParameter、VisualShaderNodeTexture2DParameter、VisualShaderNodeTexture3DParameter、VisualShaderNodeTextureParameterTriplanar等，分别对应不同纹理类型。

二、底层翻译：uniform samplerCube与着色器语言对应

该节点在 Godot 着色器语言（基于 GLSL 的 GDScript Shading Language）中被翻译为：

uniform samplerCube ...;

samplerCube是 Godot 着色器语言中的标准采样器类型，用于绑定 Cubemap 资源、以浮点方式读取。在 shading_language.rst 的类型绑定表中可以找到对应关系：samplerCube↔Cubemap，并且该表指向导入说明（Importing Images）——即你需要把图像以 Cubemap 类型导入，才能在着色器中绑定为samplerCube。

根据官方类文档，该参数节点翻译出的uniform samplerCube输出值可以被用作VisualShaderNodeCubemap的输入端口，进而完成"声明参数 → 采样纹理"的完整链路。

与全局着色器参数的关联

值得一提的是，samplerCube也可以出现在全局着色器参数（global shader uniform）中。在 class_renderingserver.rst 的GlobalShaderParameterType枚举中，GLOBAL_VAR_TYPE_SAMPLERCUBE = 27被定义为"Cubemap 采样器全局着色器参数（global uniform samplerCube ...），在编辑器 UI 中以 Cubemap 形式暴露"。这说明在 Project Settings 中定义全局 Cubemap 参数时，底层同样走的是samplerCube类型路径。

三、完整接入流程：从 ShaderMaterial 到节点

要使用该节点，需要先建立一个可视化着色器。官方教程 visual_shaders.rst 给出了标准流程：

1. 在任意 3D 对象上新建一个ShaderMaterial；
2. 为其Shader属性分配一个新的Shader资源；
3. 在打开的 Create Shader 对话框中，将Type选项改为VisualShader并命名；
4. 点击该可视化着色器打开Shader Editor（着色器编辑器）。

在着色器编辑器中，通过工具栏的Add Node按钮（或右键图形空白处）弹出节点菜单，即可在Textures分类下找到CubemapParameter节点。添加后：

• 该节点在图形上表现为一个参数节点，其输出端口类型为采样器（Sampler，端口以橙色标识，参见 visual_shaders.rst 中的端口类型表）；
• 在右侧检查器中可以为该参数命名、设置默认纹理、过滤/重复模式等；
• 通过工具栏的Show Generated Code按钮，可以直接查看该节点被翻译成的uniform samplerCube声明及其在生成着色器代码中的位置——这是验证节点行为的有效手段，也是官方推荐的学习方式。

提示：官方文档建议，即使使用可视化着色器，也应了解脚本着色器的逻辑，因为可视化图最终会被转换为脚本着色器代码（即 Shading Language），两种方式可互相印证。

四、与采样节点配合：VisualShaderNodeCubemap 的完整用法

VisualShaderNodeCubemapParameter只是"声明参数"，真正执行采样的是VisualShaderNodeCubemap节点。在 class_visualshadernodecubemap.rst 中，该采样节点被翻译为着色器语言的texture(cubemap, vec3)调用，返回一个颜色向量以及作为标量的 alpha 通道。

采样节点有三个关键属性：

• cube_map：当source为SOURCE_TEXTURE时实际采样的 Cubemap 纹理；
• source：采样源选择。
  • SOURCE_TEXTURE = 0：使用cube_map属性中设置的 Cubemap，此时samplerCube端口被忽略；
  • SOURCE_PORT = 1：使用通过samplerCube端口传入的采样器引用，此时cube_map属性被忽略；
• texture_type：定义源纹理提供的数据类型（详见下文）。

由此可以得出两种接线方式：

1. 直接采样模式：将CubemapParameter节点的samplerCube输出端口连接到VisualShaderNodeCubemap的samplerCube输入端口，并将采样节点的source设为SOURCE_PORT。这样 Cubemap 纹理可以在ShaderMaterial上按参数名灵活更换。
2. 内嵌纹理模式：不连接参数端口，直接在采样节点的cube_map属性中指定 Cubemap，source保持SOURCE_TEXTURE。

第一种方式更符合"参数化材质"的设计：同一个可视化着色器可以被多个材质复用，每个材质通过检查器或脚本为uniform samplerCube参数指定不同的 Cubemap。

采样节点的 texture_type 选项

VisualShaderNodeCubemap的texture_type枚举定义了采样结果的解释方式：

• TYPE_DATA = 0：不加任何 hint 到 uniform 声明；
• TYPE_COLOR = 1：为 uniform 声明添加source_colorhint，用于把非线性 sRGB 编码正确转换为线性编码；
• TYPE_NORMAL_MAP = 2：添加hint_normalhint，内部将纹理转换为可正确用作法线贴图的形式。

这些 hint 在底层会附加到采样器声明上，其语义与手写 GLSL 完全一致（详见第六节）。

五、继承的采样属性：过滤、重复、类型与默认颜色

由于VisualShaderNodeCubemapParameter继承自VisualShaderNodeTextureParameter，它天然拥有该类在 class_visualshadernodetextureparameter.rst 中定义的全部属性与枚举，这也正是该参数节点可调选项的完整集合：

属性	默认值	作用
texture_type	0（TYPE_DATA）	定义源纹理提供的数据类型
color_default	0（COLOR_DEFAULT_WHITE）	未给 uniform 赋纹理时的默认颜色
texture_filter	0（FILTER_DEFAULT）	纹理过滤模式
texture_repeat	0（REPEAT_DEFAULT）	纹理重复模式

各枚举的具体取值与语义如下。

texture_type（纹理数据类型）

• TYPE_DATA = 0：不加任何 hint；
• TYPE_COLOR = 1：添加source_colorhint，正确转换 sRGB → 线性；
• TYPE_NORMAL_MAP = 2：添加hint_normalhint，作为法线贴图使用；
• TYPE_ANISOTROPY = 3：添加hint_anisotropyhint，用于流向图（flowmap）；
• TYPE_MAX = 4：枚举大小标记。

color_default（无纹理时默认颜色）

• COLOR_DEFAULT_WHITE = 0：默认不透明白色；
• COLOR_DEFAULT_BLACK = 1：默认不透明黑色；
• COLOR_DEFAULT_TRANSPARENT = 2：默认全透明黑色；
• COLOR_DEFAULT_MAX = 3：枚举大小标记。

texture_filter（纹理过滤模式）

• FILTER_DEFAULT = 0：使用所附着节点确定的过滤方式；
• FILTER_NEAREST = 1：仅读取最近像素，近看呈像素化、远看因不采样 mipmap 而颗粒感明显；
• FILTER_LINEAR = 2：在最近 4 像素间混合，近看平滑、远看颗粒感明显（不采样 mipmap）；
• FILTER_NEAREST_MIPMAP = 3：最近像素 + 最近 2 级 mipmap 混合，适合可能被缩小观看的非像素艺术纹理（如 Camera2D 缩放或精灵缩放场景）；
• FILTER_LINEAR_MIPMAP = 4：4 像素间混合 + 2 级 mipmap 混合，远近均平滑；
• FILTER_NEAREST_MIPMAP_ANISOTROPIC = 5：各向异性过滤版本，近看像素化、远看平滑，对几乎与相机视线平行的表面效果更好但略慢，各向异性等级由 Project Settings 中的rendering/textures/default_filters/anisotropic_filtering_level控制；
• FILTER_LINEAR_MIPMAP_ANISOTROPIC = 6：线性各向异性版本，远近均平滑；
• FILTER_MAX = 7：枚举大小标记。

关于 mipmap 相关选项，官方文档特别提示：若 Project Settings 中rendering/textures/default_filters/use_nearest_mipmap_filter为true，则上述"混合 2 级 mipmap"会退化为"使用最近 mipmap"。另外，各向异性过滤在 2D 项目中很少有用，2D 场景通常选用FILTER_NEAREST_MIPMAP即可。

texture_repeat（纹理重复模式）

• REPEAT_DEFAULT = 0：使用节点确定重复方式；
• REPEAT_ENABLED = 1：纹理正常重复；
• REPEAT_DISABLED = 2：纹理不重复；
• REPEAT_MAX = 3：枚举大小标记。

六、参数作用域与命名

作为VisualShaderNodeParameter的子类，该节点还继承了参数节点的通用配置（见 class_visualshadernodeparameter.rst）：

• parameter_name（String，默认""）：参数名，通过该名字可在ShaderMaterial属性中访问。
• qualifier（枚举，默认0）：参数作用域：
  • QUAL_NONE = 0：参数绑定到使用该着色器的ShaderMaterial；
  • QUAL_GLOBAL = 1：参数使用 Project Settings 中定义的全局值；
  • QUAL_INSTANCE = 2：参数绑定到附有该ShaderMaterial的节点；
  • QUAL_INSTANCE_INDEX = 3：同 INSTANCE，但额外启用instance_index属性；
  • QUAL_MAX = 4：枚举大小标记。
• instance_index（int，默认0）：范围为 0–15，用于多个材质共用同一着色器时避免参数冲突。

在 GDScript 中设置该参数时需要注意：Godot 着色器语言的 uniform 类型与 GDScript 变量存在精度差异（着色器内 int/float 为 32 位，GDScript 为 64 位），类型不匹配时不会报错，但会产生未定义行为，详见 shading_language.rst 的说明。

七、配套资源：Cubemap 的导入与面顺序

要让samplerCube参数有纹理可用，需要先把图像以 Cubemap 类型导入。根据 importing_images.rst 与 class_cubemap.rst：

1. 在导入面板（Import dock）中选择Cubemap类型。Cubemap 由 6 张方形纹理以层（layers）方式组织，导入时会在面与面之间做插值（无缝 cubemap），可在自定义着色器中采样。
2. 图像面顺序必须为X+, X-, Y+, Y-, Z+, Z-（Godot 坐标系中 Y+ 为"上"，Z- 为"前"）。可使用官方提供的模板布局（2×3 为默认布局选项，另有 3×2、1×6、6×1 三种）。
3. 运行时也可通过代码创建：使用ImageTextureLayered.create_from_images()在Cubemap实例上生成。

关于 Cubemap 的典型用途，class_cubemap.rst 指出它常用于 3D 渲染中"伪造反射"（配合ReflectionProbe），让物体看起来像在反射周围环境，且通常比其它反射方案性能更好；此外也常作为天空盒使用，是自定义着色器中 uniform 的常见素材。

八、等价手写 GLSL 对照

理解了节点后，手写脚本着色器时可以完全等价地实现同样的功能。最直接的形式是把 Cubemap 作为参数声明并用texture()采样：

shader_type spatial; uniform samplerCube env_map : source_color, filter_linear_mipmap; uniform float roughness : hint_range(0.0, 1.0) = 0.5; void fragment() { // 使用反射方向对 cubemap 采样（示意：配合 view 向量计算反射） vec3 refl = reflect(-VIEW, NORMAL); vec4 color = texture(env_map, refl); ALBEDO = color.rgb; }

官方在 class_cubemap.rst 中给出了一个实用的天空盒转换示例——Godot 不支持在PanoramaSkyMaterial中直接使用 cubemap，但可以把默认的PanoramaSkyMaterial转换为ShaderMaterial（通过资源下拉菜单中的Convert to ShaderMaterial），再替换为如下代码：

shader_type sky; uniform samplerCube source_panorama : filter_linear, source_color, hint_default_black; uniform float exposure : hint_range(0, 128) = 1.0; void sky() { // 如果从其它引擎导入 cubemap，可能需要将某个 EYEDIR 分量替换为 -EYEDIR vec3 eyedir = vec3(EYEDIR.x, EYEDIR.y, EYEDIR.z); COLOR = texture(source_panorama, eyedir).rgb * exposure; }

替换保存后，在检查器的 Shader Parameters 部分为 ShaderMaterial 指定导入的 Cubemap 资源即可。这个例子恰好完整展示了uniform samplerCube声明 +texture()采样 + hint 修饰符（filter_linear、source_color、hint_default_black）的组合用法——这些正是可视化节点在后台生成的内容。

关于 hint 的完整语义，shading_language.rst 的 uniform hints 表给出了权威对照：

• source_color：标记为颜色数据，启用 sRGB → 线性转换（在 Forward+ 与 Mobile 渲染器下必需，Compatibility 下可选但官方建议始终使用）；
• hint_normal：标记为法线贴图；
• hint_anisotropy：作为流向图（flowmap），默认指向右；
• hint_default_white/hint_default_black/hint_default_transparent：未赋值时的默认颜色；
• filter[_nearest, _linear][_mipmap][_anisotropic]：指定纹理过滤；
• repeat[_enable, _disable]：指定纹理重复；
• hint_range(min, max[, step])：数值范围限制（用于int/float）。

九、与其他纹理参数节点的对比与选型建议

VisualShaderNodeTextureParameter家族覆盖了 Godot 的全部纹理类型，选择哪一个取决于你需要的采样语义：

节点	底层 uniform 类型	适用场景
VisualShaderNodeTexture2DParameter	sampler2D	常规 2D 纹理、albedo、普通贴图
VisualShaderNodeTexture2DArrayParameter	sampler2DArray	2D 纹理数组
VisualShaderNodeTexture3DParameter	sampler3D	3D 纹理（体数据）
VisualShaderNodeCubemapParameter	samplerCube	立方体贴图：天空盒、反射、环境光照
VisualShaderNodeTextureParameterTriplanar	三平面采样	地形等需要消除纹理拉伸的场景

当你需要"反射周围环境""模拟天空盒采样"或任何依赖方向向量的环境贴图查询时，VisualShaderNodeCubemapParameter就是对应的参数节点选择；结合VisualShaderNodeCubemap采样节点、Cubemap 资源导入与上文所述的属性配置，即可在可视化着色器中完成与手写 GLSLuniform samplerCube完全等价的反射/环境采样管线。

十、参考文档索引

• 本节点类参考：classes/class_visualshadernodecubemapparameter.rst
• 基类（采样属性与枚举）：classes/class_visualshadernodetextureparameter.rst
• 参数基类（作用域与命名）：classes/class_visualshadernodeparameter.rst
• 采样节点： classes/class_visualshadernodecubemap.rst
• Cubemap 资源：classes/class_cubemap.rst
• 可视化着色器入门：tutorials/shaders/visual_shaders.rst
• 着色器语言与 uniform hints：tutorials/shaders/shader_reference/shading_language.rst
• Cubemap 图像导入：tutorials/assets_pipeline/importing_images.rst
• 全局着色器参数类型（GLOBAL_VAR_TYPE_SAMPLERCUBE）：classes/class_renderingserver.rst
• 天空着色器中的samplerCube RADIANCE：tutorials/shaders/shader_reference/sky_shader.rst

赞分享

• 文档
• 教程
• 游戏开发

【免费下载链接】godot-docs

Godot Engine official documentation

项目地址：https://gitcode.com/GitHub_Trending/go/godot-docs

点击查看免费下载

相关推荐

• Material Maker 剪切（Shear）节点完全指南：原理、参数与着色器实现

  Material Maker 剪切（Shear）节点完全指南：原理、参数与着色器实现 导读 ：本文以 Shear 节点官方文档 https://link.git

  桌面应用图形学3D渲染图像处理

• Godot BackBufferCopy 节点完全指南：屏幕回读缓冲与 Screen Texture 着色器实战

  Godot BackBufferCopy 节点完全指南：屏幕回读缓冲与 Screen Texture 着色器实战 导读 BackBufferCopy 是 God

  文档教程游戏开发

• Material Maker TEX3D FBM 节点完全指南：3D 分形布朗运动噪声的原理、参数与 Godot 着色器实现

  Material Maker TEX3D FBM 节点完全指南：3D 分形布朗运动噪声的原理、参数与 Godot 着色器实现 本文基于 Material Mak

  桌面应用图形学3D渲染图像处理