Qt 6 QML中如何为立方体添加多面纹理或单张纹理映射？

错误原因分析 #

你遇到的错误Sampler qt_BaseColorMap_sampler expects a 2D texture but the associated texture is a cube map，是因为PrincipledMaterial的baseColorMap属性仅支持2D纹理，而CubeMapTexture是用于环境贴图（如天空盒、光照探针）的立方体贴图，不能直接用于模型表面的颜色纹理映射。

解决方案 #

方案1：单张纹理映射到立方体所有面 #

直接使用普通Texture替代CubeMapTexture，默认的#Cube模型会自动将2D纹理拉伸/重复到每个面：

PrincipledMaterial {
    id: basicMaterial
    baseColorMap: Texture {
        source: "maps/side.png"
        // 可选：设置纹理重复模式与过滤方式
        repeatMode: Texture.Repeat
        magnificationFilter: Texture.Linear
        minificationFilter: Texture.LinearMipMapLinear
    }
}

Model {
    id: cube
    source: "#Cube"
    materials: basicMaterial
    pickable: true
}

如果需要让单张纹理的不同区域对应立方体的不同面，需要使用纹理图集（将6个面的纹理合并到一张图中），并自定义立方体的UV坐标。这种情况需要创建自定义Mesh，或者使用第三方工具导出带正确UV的立方体模型。

方案2：为立方体每个面添加不同纹理 #

最直观的方式是用6个Plane模型拼接成立方体，每个Plane单独绑定带对应纹理的材质：

Node {
    id: cubeNode
    // 立方体边长为100，默认Plane尺寸为100x100

    // 前面
    Model {
        source: "#Plane"
        position: Qt.vector3d(0, 0, 50)
        eulerRotation.x: 180
        materials: PrincipledMaterial {
            baseColorMap: Texture { source: "maps/front.png" }
        }
    }

    // 后面
    Model {
        source: "#Plane"
        position: Qt.vector3d(0, 0, -50)
        materials: PrincipledMaterial {
            baseColorMap: Texture { source: "maps/back.png" }
        }
    }

    // 左面
    Model {
        source: "#Plane"
        position: Qt.vector3d(-50, 0, 0)
        eulerRotation.y: 90
        materials: PrincipledMaterial {
            baseColorMap: Texture { source: "maps/left.png" }
        }
    }

    // 右面
    Model {
        source: "#Plane"
        position: Qt.vector3d(50, 0, 0)
        eulerRotation.y: -90
        materials: PrincipledMaterial {
            baseColorMap: Texture { source: "maps/right.png" }
        }
    }

    // 上面
    Model {
        source: "#Plane"
        position: Qt.vector3d(0, 50, 0)
        eulerRotation.x: -90
        materials: PrincipledMaterial {
            baseColorMap: Texture { source: "maps/top.png" }
        }
    }

    // 下面
    Model {
        source: "#Plane"
        position: Qt.vector3d(0, -50, 0)
        eulerRotation.x: 90
        materials: PrincipledMaterial {
            baseColorMap: Texture { source: "maps/bottom.png" }
        }
    }
}

// 保留原有的相机、控制器逻辑
OrbitCameraController {
    origin: originNode
    camera: cameraNode
}

这种方法无需修改UV或自定义模型，每个面的纹理可独立控制，适合快速实现需求。

方案3：自定义着色器实现多纹理映射（进阶） #

如果需要更灵活的控制，可以使用ShaderEffectMaterial编写自定义GLSL着色器，通过顶点数据中的面ID或法线方向来选择不同的纹理采样。这种方式适合复杂场景，但需要掌握GLSL着色器基础。

内容的提问来源于stack exchange，提问作者Angel Palacios Mirafuentes