如何在PySide6的Qt3D（非QML）中创建Uniform Buffer Objects？

核心问题分析 #

你之前尝试用QBuffer给单个SunInfo类型的QParameter赋值无效，是因为单个uniform变量无法绑定QBuffer，QBuffer是用来绑定GLSL中的uniform block（统一块）的，而非单独的uniform变量。必须先修改着色器代码，将灯光数据定义为uniform block，再通过QBuffer传递数据。

步骤1：修改GLSL着色器代码 #

将原有的独立uniform struct改为std140布局的uniform block（std140保证内存布局固定，方便Python端打包数据）：

struct SunInfo {
    vec3    direction;
    vec3    color;
    float   intensity;
};

struct LightInfo {
    vec3    position;
    vec3    rotation;
    vec3    color;
    float   cone_inner;
    float   cone_outer;
    float   radius;
};

// 定义uniform block，指定std140布局
layout(std140) uniform LightData {
    SunInfo sun;
    LightInfo lights[MAX_NUM_LIGHTS];
};

注意：MAX_NUM_LIGHTS需要在着色器中定义（比如#define MAX_NUM_LIGHTS 4），且要和Python代码中的值保持一致。

步骤2：Python端实现UBO数据传递 #

有两种方式实现，按需选择：

方式一：手动打包字节数据（可控性高，适合复杂场景） #

利用struct模块按std140规则打包数据，直接写入QBuffer：

1. 导入依赖模块

import struct
from PySide6.Qt3DRender import QBuffer, QParameter
from PySide6.QtCore import QByteArray

2. 编写数据打包函数（严格遵循std140内存对齐）

def pack_sun_info(direction: tuple[float, float, float], 
                  color: tuple[float, float, float], 
                  intensity: float) -> bytes:
    # SunInfo总大小40字节（std140对齐要求）
    return struct.pack(
        ">fffxxxx"  # vec3 direction（12字节有效+4字节填充）
        "fffxxxx"   # vec3 color（12字节有效+4字节填充）
        "fxxxx",    # float intensity（4字节有效+4字节填充）
        *direction,
        *color,
        intensity
    )

def pack_light_info(position: tuple[float, float, float], 
                    rotation: tuple[float, float, float], 
                    color: tuple[float, float, float],
                    cone_inner: float, cone_outer: float, radius: float) -> bytes:
    # LightInfo总大小64字节（std140对齐要求）
    return struct.pack(
        ">fffxxxx"  # vec3 position（12+4）
        "fffxxxx"   # vec3 rotation（12+4）
        "fffxxxx"   # vec3 color（12+4）
        "f"         # cone_inner
        "f"         # cone_outer
        "f"         # radius
        "xxxx",     # 4字节填充到64字节
        *position,
        *rotation,
        *color,
        cone_inner,
        cone_outer,
        radius
    )

3. 打包并设置QBuffer数据

MAX_NUM_LIGHTS = 4

# 打包太阳数据
sun_data = pack_sun_info((0.0, -1.0, 0.0), (1.0, 1.0, 0.9), 1.0)

# 打包灯光数据（示例2个有效灯光，其余填充默认值）
lights_data = b""
lights_data += pack_light_info((10.0, 5.0, 0.0), (0.0, 0.0, 0.0), 
                               (1.0, 0.0, 0.0), 0.7, 0.8, 20.0)
lights_data += pack_light_info((-10.0, 5.0, 0.0), (0.0, 0.0, 0.0), 
                               (0.0, 1.0, 0.0), 0.7, 0.8, 20.0)
# 填充剩余灯光的默认数据
for _ in range(MAX_NUM_LIGHTS - 2):
    lights_data += pack_light_info((0.0, 0.0, 0.0), (0.0, 0.0, 0.0), 
                                   (0.0, 0.0, 0.0), 0.0, 0.0, 0.0)

# 拼接所有数据并写入QBuffer
total_data = sun_data + lights_data
light_buffer = QBuffer()
light_buffer.setData(QByteArray(total_data))

4. 将QBuffer绑定到uniform block并添加到材质

# 创建对应uniform block的参数
light_param = QParameter("LightData", light_buffer)
# 假设material是你的Qt3DRender.QMaterial实例
material.addParameter(light_param)

方式二：使用QShaderData（自动处理对齐，开发效率高） #

Qt3D的QShaderData会自动将Python对象的属性打包为UBO数据，无需手动处理内存对齐：

1. 定义ShaderData类

from PySide6.Qt3DRender import QShaderData

class SunShaderData(QShaderData):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.direction = (0.0, -1.0, 0.0)
        self.color = (1.0, 1.0, 0.9)
        self.intensity = 1.0

class LightShaderData(QShaderData):
    def __init__(self, position=(0.0,0.0,0.0), rotation=(0.0,0.0,0.0), 
                 color=(0.0,0.0,0.0), cone_inner=0.0, cone_outer=0.0, radius=0.0, parent=None):
        super().__init__(parent)
        self.position = position
        self.rotation = rotation
        self.color = color
        self.cone_inner = cone_inner
        self.cone_outer = cone_outer
        self.radius = radius

2. 创建数据对象并绑定到材质

MAX_NUM_LIGHTS =4

# 构建灯光数据块
light_data_block = QShaderData()
light_data_block.setProperty("sun", SunShaderData())

# 构建灯光数组
lights_list = [
    LightShaderData((10.0,5.0,0.0), (0.0,0.0,0.0), (1.0,0.0,0.0), 0.7,0.8,20.0),
    LightShaderData((-10.0,5.0,0.0), (0.0,0.0,0.0), (0.0,1.0,0.0), 0.7,0.8,20.0)
]
# 填充剩余默认灯光
for _ in range(MAX_NUM_LIGHTS -2):
    lights_list.append(LightShaderData())

light_data_block.setProperty("lights", lights_list)

# 添加到材质参数
light_param = QParameter("LightData", light_data_block)
material.addParameter(light_param)

注意事项 #

• 两种方式都需要保证Python端的变量名/属性名与GLSL中struct的成员名完全一致。
• 若需要动态更新灯光数据：
  • 方式一：重新打包数据后调用light_buffer.setData(new_data)即可。
  • 方式二：直接修改QShaderData实例的属性值，Qt3D会自动同步到GPU。
• 务必保证MAX_NUM_LIGHTS在着色器和Python代码中数值相同，避免数组越界或数据不匹配。

内容的提问来源于stack exchange，提问作者JuliuszK