企业官网建设流程全解析

textureCube()是 GLSL 中专门用于立方体贴图（cube map，即由立方体 6 个面构成的纹理）采样的纹理查询函数。本文以 The Book of Shaders 词汇表中的词条 textureCube 为主体，完整覆盖其函数声明、三个参数的含义、返回值语义与平台限制，并结合项目词汇表中与 texture2D 的同构设计、Uniforms 章节对samplerCube类型的介绍，帮助你理解“用一个三维向量采样六面纹理”的底层机制，以及 mipmap 细节级别（LOD）偏置的调节方式。

一、函数定位：它属于“纹理查询函数”一类

在词汇表总目录 glossary/README.md 中，textureCube()与texture2D()被共同归类在TEXTURE LOOKUP FUNCTIONS（纹理查询函数）主题分组下。GLSL 的纹理查询函数职责一致：给定一个采样器（sampler）和一组纹理坐标，返回对应的 texel（纹素，通常就是纹理上该位置的颜色值）。二者的区别仅在于纹理的形态：

• texture2D()面向二维纹理，采样坐标类型为vec2；
• textureCube()面向立方体贴图，采样坐标类型为vec3。

从 texture2D 词条 与 textureCube 词条 的对照可以推断，这两个函数在实现语义上完全同构：sampler参数都是“纹理所绑定到的采样器 uniform”，coord参数都是“实际执行采样的纹理坐标”，可选的bias参数都参与 mipmap 细节级别计算——只是坐标维度从 2 维提升到了 3 维。

二、函数声明（Declaration）

词条给出的标准声明如下：

vec4 textureCube(samplerCube sampler, vec3 coord) vec4 textureCube(samplerCube sampler, vec3 coord, float bias)

这里有两个重载形式：

• 两参数形式：直接以samplerCube采样器和三维坐标vec3采样；
• 三参数形式：额外接受一个float类型的bias，用于在 mipmap 细节级别计算中引入偏置。

返回类型固定为vec4，即纹素的 RGBA 颜色值。第一个参数的类型是samplerCube——这是一个与sampler2D平行的专用采样器类型（词汇表总目录将其归在 TYPES 数据分组下，与 sampler2D 并列），它只能在声明时由编译器创建，不能像普通 uniform 那样在运行时重新赋值；CPU 端通过 OpenGL 的纹理绑定机制把实际的立方体纹理“挂”到这个 sampler 上。

三、参数详解（Parameters）

1. sampler（samplerCube 类型）

sampler是已经绑定（bound）了立方体纹理的采样器。它的作用是让textureCube()能够从所绑定的纹理中取出坐标位置处的颜色。词条原文的表述是“纹理绑定到该 sampler，texel 将从中检索”。

结合本书 Uniforms 章节 的讲解：samplerCube是 shader 中 uniform 的典型数据类型之一，与float、vec2、vec3、vec4、mat2、mat3、mat4、sampler2D并列。该章节强调了两条通用规则，对声明纹理采样器同样适用：

1. uniform 必须定义在 shader 开头、设定精度（precision）之后；
2. 按业界惯例，uniform 名以u_前缀命名，让人一眼识别其身份。

据此，一个使用textureCube的片元着色器通常这样声明采样器：

#ifdef GL_ES precision mediump float; #endif uniform samplerCube u_skybox; // 绑定立方体天空盒纹理 uniform vec3 u_direction; // 采样方向（视线/法线方向） void main() { vec4 col = textureCube(u_skybox, u_direction); gl_FragColor = col; }

注意：以上示例代码是为说明用法而编写的通用片段（仓库中的示例着色器均使用程序化着色，未直接使用textureCube），其声明方式严格遵循了 Uniforms 章节 中“precision 在前、uniform 紧随其后”的规范。

2. coord（vec3 类型）

coord是指定采样位置的三维纹理坐标。对texture2D()来说，vec2坐标(u, v)直接落在纹理平面上；而对textureCube()来说，vec3坐标的含义是一个方向向量——硬件会根据该向量的分量决定：

• 落在哪一面：取绝对值最大的分量符号确定立方体六个面之一（±x、±y、±z）；
• 落在那一面上的什么位置：用另外两个分量计算该面内的二维纹理坐标。

词条的概括是“tọa độ vị trí cần lấy màu trên texture”（需要取色的纹理坐标）。理解这一点后就不难明白：textureCube()常配合视线方向或表面法线使用，这也是天空盒（skybox）渲染的基本原理——把每片元的世界空间方向送入采样器，即可取到“朝那个方向看去”的天空颜色。

3. bias（float 类型，可选）

bias是应用于level-of-detail（细节级别，LOD）计算的可选偏置量。词条的说明是：

第三个参数非必需。在根据 mipmap 各级计算出合适的细节级别之后，bias会被加上，再用于实际的纹理查找。

即执行顺序是：先由硬件依据采样坐标与屏幕覆盖范围推算出一个合适的 mipmap 级别，然后把bias加到这个级别上，最后再执行真正的纹素查找。其实际效果是：

• bias > 0：取更小、更模糊的 mipmap 级别（向远处模糊方向偏移）；
• bias < 0：取更大、更清晰的级别（向近处锐利方向偏移）；
• bias = 0：等价于不提供该参数。

如果纹理本身没有生成 mipmap，bias不会产生可见效果。这个设计与 texture2D 词条中的描述逐字对应，说明两个查询函数共享同一套 LOD 偏置机制。

四、返回值与采样语义（Description）

词条的完整描述可以归纳为三点：

1. 返回值是一个 texel，即给定坐标处纹理的（颜色）值，类型为vec4；
2. 函数的前两个输入参数分别是：类型为samplerCube的sampler（纹理所绑定到的 uniform）与类型为vec3的coord（要查找的 texel 的三维坐标）；
3. 可选的第三个输入参数为float类型的bias——在纹理带有 mipmap 并计算出合适细节级别后，先加上该偏置，再执行真正的纹理查找操作。

从 texture2D 词条 与 textureCube 词条 的措辞完全对仗的事实可以推断，textureCube()的滤波、环绕（wrap）行为等未展开的细节，与texture2D()一致，由 CPU 端为该纹理单元配置的采样状态（如线性/最近邻滤波）决定。

五、平台注意事项：iOS 上的限制

词条专门给出了一个 Side note：

在 iOS 设备上，纹理查找功能只能在 fragment shader（片元着色器）中使用。

这意味着在 iOS 的 GLSL ES 实现里，顶点着色器中无法调用纹理查询函数，textureCube()只能出现在main()的片元阶段。对编写可移植 shader 的建议是：不要假设纹理查询可以在顶点着色器中完成，把取色逻辑都放到 fragment shader 中。这一限制同样写在 texture2D 词条 中，说明它针对的是整类纹理查询函数，而非textureCube()独有。

六、与 texture2D() 的对照速查

两者声明的完整对照：

vec4 texture2D(sampler2D sampler, vec2 coord) vec4 texture2D(sampler2D sampler, vec2 coord, float bias) vec4 textureCube(samplerCube sampler, vec3 coord) vec4 textureCube(samplerCube sampler, vec3 coord, float bias)

可见两个函数是“同构异形”的关系：把sampler2D换成samplerCube、vec2换成vec3，其余语义（返回 texel、bias 参与 LOD 计算、iOS 限制）原封不动地继承过来。

七、小结与延伸阅读

textureCube()用一行代码完成了“方向 → 立方体面 → 面内坐标 → texel”的完整查找过程，是 skybox 与环境反射类效果的核心 API。掌握它需要记住三件事：采样器类型为samplerCube、坐标是三维方向向量、bias只在带 mipmap 时改变细节级别；同时牢记 iOS 上纹理查询仅限 fragment shader 的平台限制。

延伸阅读（均为本仓库内的词条与章节）：

• texture2D：二维纹理查询，与本文函数同构，词条间互为“See Also”；
• Uniforms：讲解samplerCube等 uniform 类型的声明位置与命名惯例（中文可读 03/README-ch.md）；
• Glossary 总目录：按主题与字母序索引全部词条，纹理查询函数分组位于其中；
• samplerCube 词条目录：采样器类型的词条目录（该词条正文目前仍为空模板 samplerCube/README.md，相关说明散见于各章节正文）。