En esta página

Q3DSurface Class

La clase Q3DSurface proporciona métodos para representar gráficos de superficies 3D. Más...

Cabecera: #include <Q3DSurface>
CMake: find_package(Qt6 REQUIRED COMPONENTS DataVisualization)
target_link_libraries(mytarget PRIVATE Qt6::DataVisualization)
qmake: QT += datavisualization
Desde: QtDataVisualization 1.0
Hereda: QAbstract3DGraph

Propiedades

Funciones públicas

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)

Señales

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

Descripción detallada

Esta clase permite a los desarrolladores renderizar superficies 3D y visualizarlas rotando la escena libremente. Las propiedades visuales de la superficie, como el modo de dibujo y el sombreado, pueden controlarse a través de QSurface3DSeries.

Q3DSurface admite la selección mostrando una bola resaltada en el punto de datos en el que el usuario ha hecho clic con el botón izquierdo del ratón (cuando se utiliza el controlador de entrada predeterminado) o ha seleccionado a través de QSurface3DSeries. El puntero de selección va acompañado de una etiqueta que, en el caso por defecto, muestra el valor del punto de datos y las coordenadas del punto.

El rango de valores y el formato de la etiqueta mostrada en el eje pueden controlarse a través de QValue3DAxis.

Para girar el gráfico, mantenga pulsado el botón derecho del ratón y mueva el ratón. El zoom se realiza utilizando la rueda del ratón. En ambos casos se asume que se está utilizando el manejador de entrada por defecto.

Si no se establecen ejes explícitamente en Q3DSurface, se crean ejes temporales por defecto sin etiquetas. Estos ejes por defecto pueden ser modificados a través de accesores de eje, pero tan pronto como cualquier eje se establece explícitamente para la orientación, el eje por defecto para esa orientación se destruye.

Cómo construir un gráfico Q3DSurface mínimo

En primer lugar, construir Q3DSurface. Dado que en este ejemplo estamos ejecutando el gráfico como ventana de nivel superior, necesitamos borrar la bandera Qt::FramelessWindowHint, que se establece por defecto:

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

Ahora Q3DSurface está listo para recibir datos para ser renderizados. Crear elementos de datos para recibir valores:

Primero introduce los datos en los elementos de fila y luego añade sus punteros al elemento de datos:

*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;

Crea una nueva serie y añádele datos:

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

Por último, deberá hacerla visible:

surface.show();

El código completo necesario para crear y mostrar este gráfico es:

#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();
}

Y esto es lo que producen esas pocas líneas de código:

La escena se puede rotar, hacer zoom, y se puede seleccionar un punto de la superficie para ver su posición, pero no se incluye ninguna otra interacción en este ejemplo de código mínimo. Puedes aprender más familiarizándote con los ejemplos proporcionados, como el Gráfico de superficie.

Véase también Q3DBars, Q3DScatter, y Qt Data Visualization C++ Classes.

Documentación de propiedades

axisX : QValue3DAxis*

Esta propiedad contiene el eje x activo.

Funciones de acceso:

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

Señal del notificador:

void axisXChanged(QValue3DAxis *axis)

axisY : QValue3DAxis*

Esta propiedad contiene el eje y activo.

Funciones de acceso:

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

Señal del notificador:

void axisYChanged(QValue3DAxis *axis)

axisZ : QValue3DAxis*

Esta propiedad contiene el eje z activo.

Funciones de acceso:

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

Señal del notificador:

void axisZChanged(QValue3DAxis *axis)

[since QtDataVisualization 1.2] flipHorizontalGrid : bool

Esta propiedad determina si la rejilla del eje horizontal se muestra en la parte superior del gráfico en lugar de en la parte inferior.

En algunos casos de uso, la rejilla del eje horizontal está cubierta en su mayor parte por la superficie, por lo que puede ser más útil mostrar la rejilla del eje horizontal en la parte superior del gráfico en lugar de en la parte inferior. Un caso de uso típico para esto es mostrar espectrogramas 2D utilizando la proyección ortográfica con un punto de vista de arriba hacia abajo.

Si false, la rejilla del eje horizontal y las etiquetas se dibujan sobre el fondo horizontal del gráfico. Si true, la rejilla del eje horizontal y las etiquetas se dibujan en el lado opuesto del gráfico respecto al fondo horizontal. Por defecto es false.

Esta propiedad se introdujo en QtDataVisualization 1.2.

Funciones de acceso:

bool flipHorizontalGrid() const
void setFlipHorizontalGrid(bool flip)

Señal de notificador:

void flipHorizontalGridChanged(bool flip)

[read-only] selectedSeries : QSurface3DSeries*

Esta propiedad contiene la serie seleccionada o null.

Si selectionMode tiene SelectionMultiSeries, esta propiedad contiene la serie a la que pertenece el punto seleccionado.

Funciones de acceso:

QSurface3DSeries *selectedSeries() const

Señal del notificador:

void selectedSeriesChanged(QSurface3DSeries *series)

Documentación de Funciones Miembro

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

Construye un nuevo gráfico de superficie 3D con la ventana opcional parent y la superficie format.

[virtual noexcept] Q3DSurface::~Q3DSurface()

Destruye el gráfico de superficie 3D.

void Q3DSurface::addAxis(QValue3DAxis *axis)

Añade axis al gráfico. Los ejes añadidos a través de addAxis aún no se toman para su uso, addAxis se utiliza simplemente para dar la propiedad de la axis al gráfico. El axis no debe ser nulo ni estar añadido a otro gráfico.

Véase también releaseAxis(), setAxisX(), setAxisY(), y setAxisZ().

void Q3DSurface::addSeries(QSurface3DSeries *series)

Añade series al gráfico. Un gráfico puede contener múltiples series, pero sólo tiene un conjunto de ejes. Si la serie recién añadida ha especificado un elemento seleccionado, se resaltará y se borrará cualquier selección existente. Sólo una serie añadida puede tener una selección activa.

Véase también QAbstract3DGraph::hasSeries().

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

Devuelve la lista de todos los ejes añadidos.

Véase también addAxis().

void Q3DSurface::releaseAxis(QValue3DAxis *axis)

Devuelve la propiedad de axis a quien lo solicitó, si se ha añadido a este gráfico. Si el axis liberado está en uso, se creará un nuevo eje por defecto y se activará.

Si el eje por defecto se libera y se vuelve a añadir más tarde, se comporta como cualquier otro eje.

Véase también addAxis(), setAxisX(), setAxisY() y setAxisZ().

void Q3DSurface::removeSeries(QSurface3DSeries *series)

Elimina la dirección series del gráfico.

Véase también QAbstract3DGraph::hasSeries().

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

Devuelve la lista de series añadidas a este gráfico.

Véase también QAbstract3DGraph::hasSeries().

void Q3DSurface::setAxisX(QValue3DAxis *axis)

Establece axis como el eje x activo. Llama implícitamente a addAxis() para transferir la propiedad del eje a este gráfico.

Si axis es nulo, se crea un eje temporal por defecto sin etiquetas y con un rango que se ajusta automáticamente.

Este eje temporal se destruye si se establece explícitamente otro eje con la misma orientación.

Nota: Función setter para la propiedad axisX.

Véase también axisX(), addAxis(), y releaseAxis().

void Q3DSurface::setAxisY(QValue3DAxis *axis)

Establece axis como el eje y activo. Llama implícitamente a addAxis() para transferir la propiedad del eje a este gráfico.

Si axis es nulo, se crea un eje temporal por defecto sin etiquetas y con un rango que se ajusta automáticamente.

Este eje temporal se destruye si se establece explícitamente otro eje con la misma orientación.

Nota: Función setter para la propiedad axisY.

Véase también axisY(), addAxis(), y releaseAxis().

void Q3DSurface::setAxisZ(QValue3DAxis *axis)

Establece axis como el eje z activo. Llama implícitamente a addAxis() para transferir la propiedad del eje a este gráfico.

Si axis es nulo, se crea un eje temporal por defecto sin etiquetas y con un rango que se ajusta automáticamente.

Este eje temporal se destruye si se establece explícitamente otro eje con la misma orientación.

Nota: Función setter para la propiedad axisZ.

Véase también axisZ(), addAxis(), y 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.