Sur cette page

Q3DSurface Class

La classe Q3DSurface fournit des méthodes de rendu des tracés de surface 3D. Plus d'informations...

En-tête : #include <Q3DSurface>
CMake : find_package(Qt6 REQUIRED COMPONENTS DataVisualization)
target_link_libraries(mytarget PRIVATE Qt6::DataVisualization)
qmake : QT += datavisualization
Depuis : QtDataVisualization 1.0
Hérite : QAbstract3DGraph

Propriétés

Fonctions publiques

Q3DSurface(const QSurfaceFormat *format = nullptr, QWindow *parent = nullptr)
virtual ~Q3DSurface()
void addAxis(QValue3DAxis *axis)
void addSeries(QSurface3DSeries *series)
QList<QValue3DAxis *> axes() const
QValue3DAxis *axisX() const
QValue3DAxis *axisY() const
QValue3DAxis *axisZ() const
bool flipHorizontalGrid() const
void releaseAxis(QValue3DAxis *axis)
void removeSeries(QSurface3DSeries *series)
QSurface3DSeries *selectedSeries() const
QList<QSurface3DSeries *> seriesList() const
void setAxisX(QValue3DAxis *axis)
void setAxisY(QValue3DAxis *axis)
void setAxisZ(QValue3DAxis *axis)
void setFlipHorizontalGrid(bool flip)

Signaux

void axisXChanged(QValue3DAxis *axis)
void axisYChanged(QValue3DAxis *axis)
void axisZChanged(QValue3DAxis *axis)
void flipHorizontalGridChanged(bool flip)
void selectedSeriesChanged(QSurface3DSeries *series)

Description détaillée

Cette classe permet aux développeurs de rendre des tracés de surface en 3D et de les visualiser en faisant pivoter la scène librement. Les propriétés visuelles de la surface, telles que le mode de dessin et l'ombrage, peuvent être contrôlées via QSurface3DSeries.

La Q3DSurface prend en charge la sélection en affichant une boule en surbrillance sur le point de données sur lequel l'utilisateur a cliqué avec le bouton gauche de la souris (lorsque le gestionnaire d'entrée par défaut est utilisé) ou qu'il a sélectionné via QSurface3DSeries. Le pointeur de sélection est accompagné d'une étiquette qui, par défaut, indique la valeur du point de données et ses coordonnées.

La plage de valeurs et le format de l'étiquette affichée sur l'axe peuvent être contrôlés via QValue3DAxis.

Pour faire pivoter le graphique, maintenez le bouton droit de la souris enfoncé et déplacez la souris. Le zoom s'effectue à l'aide de la molette de la souris. Dans les deux cas, on suppose que le gestionnaire d'entrée par défaut est utilisé.

Si aucun axe n'est défini explicitement pour Q3DSurface, des axes temporaires par défaut sans étiquette sont créés. Ces axes par défaut peuvent être modifiés via les accesseurs d'axe, mais dès qu'un axe est défini explicitement pour l'orientation, l'axe par défaut pour cette orientation est détruit.

Comment construire un graphe Q3DSurface minimal ?

Commencez par construire Q3DSurface. Puisque nous exécutons le graphique en tant que fenêtre de premier niveau dans cet exemple, nous devons désactiver le drapeau Qt::FramelessWindowHint, qui est activé par défaut :

Q3DSurface surface;
surface.setFlags(surface.flags() ^ Qt::FramelessWindowHint);

Q3DSurface est maintenant prêt à recevoir des données à rendre. Créez des éléments de données pour recevoir des valeurs :

Introduisez d'abord les données dans les éléments de ligne, puis ajoutez leurs pointeurs à l'élément de données :

*dataRow1 << QVector3D(0.0f, 0.1f, 0.5f) << QVector3D(1.0f, 0.5f, 0.5f);
*dataRow2 << QVector3D(0.0f, 1.8f, 1.0f) << QVector3D(1.0f, 1.2f, 1.0f);
*data << dataRow1 << dataRow2;

Créez une nouvelle série et attribuez-lui des données :

QSurface3DSeries *series = new QSurface3DSeries;
series->dataProxy()->resetArray(data);
surface.addSeries(series);

Enfin, vous devrez la rendre visible :

surface.show();

Le code complet nécessaire à la création et à l'affichage de ce graphique est le suivant :

#include <QtDataVisualization>

int main(int argc, char **argv)
{
    qputenv("QSG_RHI_BACKEND", "opengl");
    QGuiApplication app(argc, argv);

    Q3DSurface surface;
    surface.setFlags(surface.flags() ^ Qt::FramelessWindowHint);
    QSurfaceDataArray *data = new QSurfaceDataArray;
    QSurfaceDataRow *dataRow1 = new QSurfaceDataRow;
    QSurfaceDataRow *dataRow2 = new QSurfaceDataRow;

    *dataRow1 << QVector3D(0.0f, 0.1f, 0.5f) << QVector3D(1.0f, 0.5f, 0.5f);
    *dataRow2 << QVector3D(0.0f, 1.8f, 1.0f) << QVector3D(1.0f, 1.2f, 1.0f);
    *data << dataRow1 << dataRow2;

    QSurface3DSeries *series = new QSurface3DSeries;
    series->dataProxy()->resetArray(data);
    surface.addSeries(series);
    surface.show();

    return app.exec();
}

Et voici ce que ces quelques lignes de code produisent :

La scène peut être tournée, zoomée et un point de la surface peut être sélectionné pour voir sa position, mais aucune autre interaction n'est incluse dans cet exemple de code minimal. Vous pouvez en apprendre davantage en vous familiarisant avec les exemples fournis, comme le graphique de surface.

Voir aussi Q3DBars, Q3DScatter, et Qt Data Visualization C++ Classes.

Documentation sur les propriétés

axisX : QValue3DAxis*

Cette propriété contient l'axe des x actif.

Fonctions d'accès :

QValue3DAxis *axisX() const
void setAxisX(QValue3DAxis *axis)

Signal de notification :

void axisXChanged(QValue3DAxis *axis)

axisY : QValue3DAxis*

Cette propriété contient l'axe des ordonnées actif.

Fonctions d'accès :

QValue3DAxis *axisY() const
void setAxisY(QValue3DAxis *axis)

Signal de notification :

void axisYChanged(QValue3DAxis *axis)

axisZ : QValue3DAxis*

Cette propriété contient l'axe z actif.

Fonctions d'accès :

QValue3DAxis *axisZ() const
void setAxisZ(QValue3DAxis *axis)

Signal de notification :

void axisZChanged(QValue3DAxis *axis)

[since QtDataVisualization 1.2] flipHorizontalGrid : bool

Cette propriété indique si la grille de l'axe horizontal est affichée en haut du graphique plutôt qu'en bas.

Dans certains cas d'utilisation, la grille de l'axe horizontal est principalement couverte par la surface, il peut donc être plus utile d'afficher la grille de l'axe horizontal en haut du graphique plutôt qu'en bas. Un cas d'utilisation typique est l'affichage de spectrogrammes 2D à l'aide de la projection orthographique avec un point de vue de haut en bas.

Si false, la grille de l'axe horizontal et les étiquettes sont dessinées sur le fond horizontal du graphique. Si true, la grille et les étiquettes de l'axe horizontal sont dessinées sur le côté opposé du graphique par rapport à l'arrière-plan horizontal. La valeur par défaut est false.

Cette propriété a été introduite dans QtDataVisualization 1.2.

Fonctions d'accès :

bool flipHorizontalGrid() const
void setFlipHorizontalGrid(bool flip)

Signal Notifier :

void flipHorizontalGridChanged(bool flip)

[read-only] selectedSeries : QSurface3DSeries*

Cette propriété contient la série sélectionnée ou null.

Si le mode de sélection a été défini sur SelectionMultiSeries, cette propriété contient la série qui possède le point sélectionné.

Fonctions d'accès :

QSurface3DSeries *selectedSeries() const

Signal Notifier :

void selectedSeriesChanged(QSurface3DSeries *series)

Member Function Documentation

[explicit] Q3DSurface::Q3DSurface(const QSurfaceFormat *format = nullptr, QWindow *parent = nullptr)

Construit un nouveau graphique de surface 3D avec la fenêtre parent et la surface format.

[virtual noexcept] Q3DSurface::~Q3DSurface()

Détruit le graphe de surface 3D.

void Q3DSurface::addAxis(QValue3DAxis *axis)

Ajoute axis au graphique. Les axes ajoutés via addAxis ne sont pas encore utilisés, addAxis est simplement utilisé pour donner la propriété de axis au graphique. L'adresse axis ne doit pas être nulle ou ajoutée à un autre graphique.

Voir aussi releaseAxis(), setAxisX(), setAxisY() et setAxisZ().

void Q3DSurface::addSeries(QSurface3DSeries *series)

Ajoute le site series au graphique. Un graphique peut contenir plusieurs séries, mais n'a qu'un seul ensemble d'axes. Si la série nouvellement ajoutée a spécifié un élément sélectionné, elle sera mise en évidence et toute sélection existante sera effacée. Une seule série ajoutée peut avoir une sélection active.

Voir également QAbstract3DGraph::hasSeries().

QList<QValue3DAxis *> Q3DSurface::axes() const

Renvoie la liste de tous les axes ajoutés.

Voir aussi addAxis().

void Q3DSurface::releaseAxis(QValue3DAxis *axis)

Libère la propriété du site axis à l'appelant, s'il est ajouté à ce graphique. Si l'adresse axis libérée est utilisée, un nouvel axe par défaut sera créé et activé.

Si l'axe par défaut est libéré et ajouté plus tard, il se comporte comme n'importe quel autre axe.

Voir également addAxis(), setAxisX(), setAxisY() et setAxisZ().

void Q3DSurface::removeSeries(QSurface3DSeries *series)

Supprime le site series du graphique.

Voir aussi QAbstract3DGraph::hasSeries().

QList<QSurface3DSeries *> Q3DSurface::seriesList() const

Renvoie la liste des séries ajoutées à ce graphique.

Voir également QAbstract3DGraph::hasSeries().

void Q3DSurface::setAxisX(QValue3DAxis *axis)

Définit axis comme l'axe des x actif. Appelle implicitement addAxis() pour transférer la propriété de l'axe à ce graphique.

Si axis est nul, un axe temporaire par défaut sans étiquette et avec une plage qui s'ajuste automatiquement est créé.

Cet axe temporaire est détruit si un autre axe est défini explicitement avec la même orientation.

Remarque : fonction de définition de la propriété axisX.

Voir également axisX(), addAxis() et releaseAxis().

void Q3DSurface::setAxisY(QValue3DAxis *axis)

Définit axis comme axe des ordonnées actif. Appelle implicitement addAxis() pour transférer la propriété de l'axe à ce graphique.

Si axis est nul, un axe temporaire par défaut sans étiquette et avec une plage qui s'ajuste automatiquement est créé.

Cet axe temporaire est détruit si un autre axe est défini explicitement avec la même orientation.

Remarque : fonction de définition de la propriété axisY.

Voir également axisY(), addAxis() et releaseAxis().

void Q3DSurface::setAxisZ(QValue3DAxis *axis)

Définit axis comme l'axe z actif. Appelle implicitement addAxis() pour transférer la propriété de l'axe à ce graphique.

Si axis est nul, un axe temporaire par défaut sans étiquette et avec une plage qui s'ajuste automatiquement est créé.

Cet axe temporaire est détruit si un autre axe est défini explicitement avec la même orientation.

Remarque : fonction de définition de la propriété axisZ.

Voir également axisZ(), addAxis() et releaseAxis().

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.