PySide6.QtQuick3D.QQuick3DGeometry¶

class QQuick3DGeometry¶

用于定义自定义几何体的基类。More_…

概要¶

方法¶

• def __init__()

• def addAttribute()

• def addSubset()

• def addTargetAttribute()

• def attribute()

• def attributeCount()

• def boundsMax()

• def boundsMin()

• def clear()

• def indexData()

• def primitiveType()

• def setBounds()

• def setIndexData()

• def setPrimitiveType()

• def setStride()

• def setTargetData()

• def setVertexData()

• def stride()

• def subsetBoundsMax()

• def subsetBoundsMin()

• def subsetCount()

• def subsetName()

• def subsetOffset()

• def targetAttribute()

• def targetAttributeCount()

• def targetData()

• def vertexData()

信号¶

• def geometryChanged()

• def geometryNodeDirty()

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述¶

QQuick3DGeometry 可用于为 Qt Quick 3D 场景中的模型指定自定义几何体。

虽然不是严格要求的，但典型的用法是从这个类继承。然后通过将子类注册到类型系统中，将其暴露给QML。然后可以将模型的geometry属性设置为引用注册类型的实例。

这种类的高级结构通常类似于以下内容：

class CustomGeometry : public QQuick3DGeometry
{
public:
    CustomGeometry() { rebuildGeometry(); }

    void setSomething() {
       // Change relevant internal data.
       // ...

       // Then rebuild the vertex and index data and pass it to QQuick3DGeometry.
       rebuildGeometry();

       // Finally, trigger an update. This is relevant in case nothing else
       // is changing in the scene; this way we make sure a new frame will
       // be rendered.
       update();
    }

private:
    void rebuildGeometry()
    {
        QByteArray vertices;
        QByteArray indices;
        ...
        setPrimitiveType(Lines);
        setVertexBuffer(vertices);
        setIndexBuffer(indices);
        setStride(3 * sizeof(float)); // e.g. when having 3 components per vertex
        setBounds(...); // minimum and maximum extents, for picking
        addAttribute(PositionSemantic, 0, F32Type);
        ...
    }
};

这个类可以注册为QML类型，并与Model一起使用。

在 Qt 5 中，类型注册是通过 qmlRegisterType 进行的：

qmlRegisterType<CustomGeometry>("Example", 1, 0, "CustomGeometry");

在 Qt 6 中，默认方法是借助构建系统使用自动注册。现在，.pro 文件可以包含以下内容，而不是调用 qmlRegisterType：

CONFIG += qmltypes
QML_IMPORT_NAME = Example
QML_IMPORT_MAJOR_VERSION = 1

使用CMake时，自动注册是默认行为，因此除了基本的QML模块设置外，不需要特殊设置：

qt_add_qml_module(application
    URI Example
    VERSION 1.0
)

类实现应添加 QML_NAMED_ELEMENT：

class CustomGeometry : public QQuick3DGeometry
{
    Q_OBJECT
    QML_NAMED_ELEMENT(CustomGeometry)
    ...
};

然后，QML代码可以使用自定义类型：

import Example 1.0

Model {
    id: customModel
    geometry: CustomGeometry {
    }
}

至少，自定义几何体应指定以下内容：

• 顶点数据，

• 顶点步幅，

• 原始类型，

• 一个具有PositionSemantic属性的属性。

这些足以渲染网格。对于索引绘制，还需要指定索引缓冲区数据和具有IndexSemantic的属性。为了支持拾取（输入），类必须使用setBounds()指定边界体积。为了正确的光照，需要一个具有NormalSemantic的属性。当材质使用纹理时，必须提供至少一组UV坐标，并在TexCoord0Semantic或TexCoord1Semantic属性中描述。某些材质可能还需要切线和副法线。

作为一个具体且最小的示例，以下类将提供单个三角形的几何形状：

class ExampleGeometry : public QQuick3DGeometry
{
    Q_OBJECT
    QML_NAMED_ELEMENT(ExampleGeometry)

public:
    ExampleGeometry();

private:
    void updateData();
};

ExampleGeometry::ExampleGeometry()
{
    updateData();
}

void ExampleGeometry::updateData()
{
    QByteArray v;
    v.resize(3 * 3 * sizeof(float));
    float *p = reinterpret_cast<float *>(v.data());

    // a triangle, front face = counter-clockwise
    *p++ = -1.0f; *p++ = -1.0f; *p++ = 0.0f;
    *p++ = 1.0f; *p++ = -1.0f; *p++ = 0.0f;
    *p++ = 0.0f; *p++ = 1.0f; *p++ = 0.0f;

    setVertexData(v);
    setStride(3 * sizeof(float));

    setPrimitiveType(QQuick3DGeometry::PrimitiveType::Triangles);

    addAttribute(QQuick3DGeometry::Attribute::PositionSemantic,
                 0,
                 QQuick3DGeometry::Attribute::F32Type);
}

根据场景中的光照，从模型引用此几何体的结果：

注意

顶点数据应遵循OpenGL的约定。这意味着在提供数据时，必须假设在归一化设备坐标系中Y轴指向上方，并且前表面具有逆时针方向的环绕。

另请参阅

Model Geometry

class PrimitiveType¶

__init__([parent=None])¶

Parameters:

父级 – QQuick3DObject

addAttribute(att)¶

Parameters:

att – 属性

这是一个重载函数。

添加顶点属性描述。每个属性都有一个语义，指定属性的用途及其组件数量，从顶点开始到属性位置的偏移量，以及指定属性数据类型和大小的componentType。

addAttribute(semantic, offset, componentType)

Parameters:

• 语义 – Semantic

• offset – int

• componentType – ComponentType

添加顶点属性描述。每个属性都有一个语义，它指定了属性的用途及其组件的数量，一个偏移量，从顶点开始到顶点内部属性位置的偏移量，以及一个组件类型，指定属性的数据类型和大小。

语义可以是以下之一：

• 位置语义

• 该属性是一个位置。包含3个分量：x、y 和 z

此外，semantic 可以是 IndexSemantic。在这种情况下，该属性不代表顶点缓冲区中的条目，而是描述索引缓冲区中的索引数据。由于每个顶点只有一个索引，offset 对索引缓冲区没有意义，应保持为零。

组件类型可以是以下之一：

• U16类型

• 索引组件类型是无符号16位整数。仅支持IndexSemantic。

注意

联合索引数据通常是I32Type。为了与不支持整数顶点输入属性的API（如OpenGL ES 2.0）一起工作，也支持F32Type。

注意

对于索引数据（IndexSemantic），只有U16Type和U32Type是合理且受支持的。

注意

TargetXXXSemantics 将被弃用。addTargetAttribute 可以用于形态目标。现在这些语义仅为了向后兼容而支持。如果它们与 addTargetAttribute 和 setTargetData 混合使用，结果无法保证。

addSubset(offset, count, boundsMin, boundsMax[, name={}])¶

Parameters:

• offset – int

• count – int

• boundsMin – QVector3D

• boundsMax – QVector3D

• name – str

向几何体添加新的子集。子集允许使用不同的材质渲染几何体的部分。材质在model中指定。

如果几何体有索引缓冲区，那么offset和count是子集中索引的原始偏移量和计数。如果几何体只有顶点缓冲区，则偏移量是顶点偏移量，计数是子集中的顶点数量。

边界 boundsMin 和 boundsMax 应该像几何边界一样包围子集。此外，子集可以有一个 name。

addTargetAttribute(att)¶

Parameters:

att – TargetAttribute

这是一个重载函数。

添加变形目标属性描述。每个属性都有一个目标ID，表示该属性所属的目标，一个语义，指定属性的用途及其组件数量，一个从顶点开始到属性位置的偏移量，以及一个表示元素之间字节大小的步幅。

addTargetAttribute(targetId, semantic, offset[, stride=0])

Parameters:

• targetId – int

• 语义 – Semantic

• offset – int

• stride – 整数

添加变形目标属性描述。每个属性都有一个targetId，表示该属性所属的目标，一个semantic，指定属性的用途及其组件数量，一个offset，表示从顶点开始到属性位置的偏移量，以及一个stride，表示元素之间的字节大小。

注意

targetId 应从 0 开始递增，不能跳过任何数字，并且所有目标应具有相同的属性。

注意

语义与顶点属性相同，但目标属性不允许使用IndexSemantic、JointSementic和WeightSemantic。

注意

所有目标属性的componentTypes必须是F32Type。

注意

如果未给出步幅或步幅小于或等于零，则该属性被视为紧密打包。

另请参阅

addAttribute

attribute(index)¶

Parameters:

索引 – int

Return type:

属性

返回属性定义编号 index

属性定义从0编号到attributeCount() - 1

attributeCount()¶

Return type:

整数

返回为此几何定义的属性数量。

另请参阅

attribute

boundsMax()¶

Return type:

QVector3D

返回边界体积的最大坐标。

另请参阅

setBounds

boundsMin()¶

Return type:

QVector3D

返回边界体积的最小坐标。

另请参阅

setBounds

clear()¶

将几何体重置为其初始状态，清除先前设置的顶点和索引数据以及属性。

geometryChanged()¶

geometryNodeDirty()¶

indexData()¶

Return type:

QByteArray

返回索引缓冲区数据。

另请参阅

setIndexData()

primitiveType()¶

Return type:

PrimitiveType

返回渲染时使用的原始类型。默认是Triangles。

另请参阅

setPrimitiveType

setBounds(min, max)¶

Parameters:

• min – QVector3D

• max – QVector3D

将几何体的边界体积设置为由点min和max定义的立方体。这用于picking。

setIndexData(data)¶

Parameters:

数据 – QByteArray

将索引缓冲区设置为data。要使用索引绘制，请添加一个带有IndexSemantic的属性

另请参阅

indexData() addAttribute

setIndexData(offset, data)

Parameters:

• offset – int

• data – QByteArray

这是一个重载函数。

更新索引缓冲区的一个子集。offset 指定字节偏移量，data 指定大小和数据。

此函数不会调整缓冲区的大小。如果offset + data.size()大于缓冲区的当前大小，超出部分的数据将被忽略。

注意

顶点、索引和变形目标数据的部分更新函数不保证这些更改在内部是如何实现的。根据底层实现的不同，即使是部分更改也可能导致更新整个图形资源。

setPrimitiveType(type)¶

Parameters:

类型 – PrimitiveType

设置用于渲染的原始类型为type。

• 积分

• 基本元素是点。

初始值为 Triangles。

注意

请注意，三角形扇（TriangleFan）在运行时可能不受支持，这取决于底层的图形API。例如，使用Direct 3D时，这种拓扑结构将完全无法使用。

注意

点和线的点大小以及线宽由material控制。但请注意，根据底层图形API的不同，运行时可能不支持除1以外的其他大小。

另请参阅

primitiveType()

setStride(stride)¶

Parameters:

步幅 – int

将顶点缓冲区的步幅设置为stride，以字节为单位。这是缓冲区中两个连续顶点之间的距离。

例如，一个使用PositionSemantic、IndexSemantic和ColorSemantic的几何体的紧密打包、交错顶点缓冲区的步幅将为28（总共七个浮点数：三个用于位置，四个用于颜色，没有用于索引，索引不进入顶点缓冲区。）

注意

QQuick3DGeometry 期望并且仅适用于具有交错属性布局的顶点数据。

另请参阅

stride() addAttribute

setTargetData(data)¶

Parameters:

数据 – QByteArray

设置变形目标缓冲区的data。缓冲区应包含所有变形目标数据。

另请参阅

targetData() addTargetAttribute

setTargetData(offset, data)

Parameters:

• offset – int

• data – QByteArray

这是一个重载函数。

更新变形目标缓冲区的子集。offset 指定字节偏移量，data 指定大小和数据。

此函数不会调整缓冲区的大小。如果offset + data.size()大于缓冲区的当前大小，超出部分的数据将被忽略。

注意

顶点、索引和变形目标数据的部分更新函数不保证这些更改在内部是如何实现的。根据底层实现的不同，即使是部分更改也可能导致更新整个图形资源。

setVertexData(data)¶

Parameters:

数据 – QByteArray

设置顶点缓冲区data。缓冲区应包含数组中打包的所有顶点数据，如属性定义所述。请注意，这不包括具有IndexSemantic的属性，这些属性属于索引缓冲区。

另请参阅

vertexData() addAttribute setStride setIndexData

setVertexData(offset, data)

Parameters:

• offset – int

• data – QByteArray

这是一个重载函数。

更新顶点缓冲区的一个子集。offset 指定字节偏移量，data 指定大小和数据。

此函数不会调整缓冲区的大小。如果offset + data.size()大于缓冲区的当前大小，超出部分的数据将被忽略。

注意

顶点、索引和变形目标数据的部分更新函数不保证这些更改在内部是如何实现的。根据底层实现的不同，即使是部分更改也可能导致更新整个图形资源。

stride()¶

Return type:

整数

返回顶点缓冲区的字节步长。

另请参阅

setStride

subsetBoundsMax(subset)¶

Parameters:

subset – 整数

Return type:

QVector3D

返回subset的最大边界数。

另请参阅

subsetBoundsMin

subsetBoundsMin(subset)¶

Parameters:

subset – 整数

Return type:

QVector3D

返回subset的最小边界数量。

另请参阅

subsetBoundsMax

subsetCount()¶

Return type:

整数

返回子集的数量。

subsetCount(subset)

Parameters:

subset – 整数

Return type:

整数

返回子集基元计数。

另请参阅

subsetOffset

subsetName(subset)¶

Parameters:

subset – 整数

Return type:

字符串

返回subset名称。

subsetOffset(subset)¶

Parameters:

subset – 整数

Return type:

整数

返回顶点或索引缓冲区的subset偏移量。

另请参阅

subsetCount

targetAttribute(index)¶

Parameters:

索引 – int

Return type:

TargetAttribute

返回形态目标属性定义编号 index

属性定义从0编号到attributeCount() - 1

targetAttributeCount()¶

Return type:

整数

返回为此几何体定义的变形目标属性的数量。

另请参阅

targetAttribute

targetData()¶

Return type:

QByteArray

返回由setTargetData设置的目标缓冲区数据集。

另请参阅

setTargetData()

vertexData()¶

Return type:

QByteArray

返回由setVertexData设置的顶点缓冲区数据。

另请参阅

setVertexData()

class Attribute¶

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述¶

class Semantic¶

class ComponentType¶

PySide6.QtQuick3D.QQuick3DGeometry.Attribute.semantic¶

PySide6.QtQuick3D.QQuick3DGeometry.Attribute.offset¶

PySide6.QtQuick3D.QQuick3DGeometry.Attribute.componentType¶

class TargetAttribute¶

在版本6.6中添加。

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述¶

PySide6.QtQuick3D.QQuick3DGeometry.TargetAttribute.targetId¶

PySide6.QtQuick3D.QQuick3DGeometry.TargetAttribute.attr¶

PySide6.QtQuick3D.QQuick3DGeometry.TargetAttribute.stride¶