En esta página

QCustom3DVolume Class

La clase QCustom3DVolume añade un objeto volumen renderizado a un gráfico. Más...

Cabecera: #include <QCustom3DVolume>
CMake: find_package(Qt6 REQUIRED COMPONENTS Graphs)
target_link_libraries(mytarget PRIVATE Qt6::Graphs)
qmake: QT += graphs
En QML: Custom3DVolume
Hereda: QCustom3DItem

Propiedades

Funciones públicas

QCustom3DVolume(QObject *parent = nullptr)
QCustom3DVolume(QVector3D position, QVector3D scaling, const QQuaternion &rotation, int textureWidth, int textureHeight, int textureDepth, QList<uchar> *textureData, QImage::Format textureFormat, const QList<QRgb> &colorTable, QObject *parent = nullptr)
virtual ~QCustom3DVolume() override
float alphaMultiplier() const
QList<QRgb> colorTable() const
QList<uchar> *createTextureData(const QList<QImage *> &images)
bool drawSliceFrames() const
bool drawSlices() const
bool preserveOpacity() const
QImage renderSlice(Qt::Axis axis, int index)
void setAlphaMultiplier(float mult)
void setColorTable(const QList<QRgb> &colors)
void setDrawSliceFrames(bool enable)
void setDrawSlices(bool enable)
void setPreserveOpacity(bool enable)
void setSliceFrameColor(QColor color)
void setSliceFrameGaps(QVector3D values)
void setSliceFrameThicknesses(QVector3D values)
void setSliceFrameWidths(QVector3D values)
void setSliceIndexX(int value)
void setSliceIndexY(int value)
void setSliceIndexZ(int value)
void setSliceIndices(int x, int y, int z)
void setSubTextureData(Qt::Axis axis, int index, const QImage &image)
void setSubTextureData(Qt::Axis axis, int index, const uchar *data)
void setTextureData(QList<uchar> *data)
void setTextureDepth(int value)
void setTextureDimensions(int width, int height, int depth)
void setTextureFormat(QImage::Format format)
void setTextureHeight(int value)
void setTextureWidth(int value)
void setUseHighDefShader(bool enable)
QColor sliceFrameColor() const
QVector3D sliceFrameGaps() const
QVector3D sliceFrameThicknesses() const
QVector3D sliceFrameWidths() const
int sliceIndexX() const
int sliceIndexY() const
int sliceIndexZ() const
QList<uchar> *textureData() const
int textureDataWidth() const
int textureDepth() const
QImage::Format textureFormat() const
int textureHeight() const
int textureWidth() const
bool useHighDefShader() const

Señales

void alphaMultiplierChanged(float mult)
void colorTableChanged()
void drawSliceFramesChanged(bool enabled)
void drawSlicesChanged(bool enabled)
void preserveOpacityChanged(bool enabled)
void sliceFrameColorChanged(QColor color)
void sliceFrameGapsChanged(QVector3D values)
void sliceFrameThicknessesChanged(QVector3D values)
void sliceFrameWidthsChanged(QVector3D values)
void sliceIndexXChanged(int value)
void sliceIndexYChanged(int value)
void sliceIndexZChanged(int value)
void textureDataChanged(QList<uchar> *data)
void textureDepthChanged(int value)
void textureFormatChanged(QImage::Format format)
void textureHeightChanged(int value)
void textureWidthChanged(int value)
void useHighDefShaderChanged(bool enabled)

Descripción detallada

Un objeto de volumen renderizado es una caja con una textura 3D. Se admiten tres planos de corte para el volumen, uno a lo largo de cada eje principal del volumen.

El renderizado de objetos de volumen es muy intensivo en rendimiento, especialmente cuando el volumen es muy transparente, ya que el contenido del volumen es trazado por rayos. El rendimiento aumenta casi linealmente con la cantidad de píxeles que ocupa el volumen en la pantalla, por lo que mostrar el volumen en una vista más pequeña o limitar el nivel de zoom del gráfico son formas sencillas de mejorar el rendimiento. Del mismo modo, las dimensiones de la textura del volumen tienen un gran impacto en el rendimiento. Si la velocidad de fotogramas es más importante que el renderizado pixel-perfect del contenido del volumen, considera desactivar el shader de alta definición estableciendo la propiedad useHighDefShader en false.

Nota: Los objetos volumétricos utilizan texturas 3D, que no son compatibles con los entornos OpenGL ES2.

Nota: Sólo se admiten dos formatos: QImage::Format_Indexed8 y QImage::Format_ARGB32. Si se especifica un formato indexado, también debe establecerse colorTable. Por defecto es QImage::Format_ARGB32.

Véase también Q3DGraphsWidgetItem::addCustomItem() y useHighDefShader.

Documentación de propiedades

alphaMultiplier : float

Esta propiedad contiene el valor por el que se multiplica el valor alfa de cada texel de la textura del volumen en el momento del renderizado.

Esta propiedad puede utilizarse para introducir una transparencia uniforme en el volumen. Si preserveOpacity es true, sólo se verán afectados los texels con al menos algo de transparencia al principio, y los texels totalmente opacos no se verán afectados. El valor no debe ser negativo. Por defecto es 1.0f.

Funciones de acceso:

float alphaMultiplier() const
void setAlphaMultiplier(float mult)

Señal notificadora:

void alphaMultiplierChanged(float mult)

Véase también preserveOpacity y textureData.

colorTable : QList<QRgb>

Esta propiedad contiene la matriz que contiene los colores para los formatos de textura indexados.

Si el formato de textura no está indexado, esta matriz no se utiliza y puede estar vacía.

Por defecto es 0.

Funciones de acceso:

QList<QRgb> colorTable() const
void setColorTable(const QList<QRgb> &colors)

Señal notificadora:

void colorTableChanged()

Véase también textureData, setTextureFormat(), y QImage::colorTable().

drawSliceFrames : bool

Esta propiedad indica si los marcos de las rodajas se dibujan alrededor del volumen.

Si el valor de esta propiedad es true, los marcos de los cortes indicados por las propiedades de índice de corte se dibujarán alrededor del volumen. Si es false, no se dibujará ningún marco de corte.

Dibujar marcos de corte es independiente de dibujar cortes, por lo que puedes mostrar el volumen completo y dibujar los marcos de corte a su alrededor. Esto es útil cuando se utiliza renderSlice() para mostrar los cortes fuera del propio gráfico.

Por defecto es false.

Funciones de acceso:

bool drawSliceFrames() const
void setDrawSliceFrames(bool enable)

Señal notificadora:

void drawSliceFramesChanged(bool enabled)

Véase también sliceIndexX, sliceIndexY, sliceIndexZ, drawSlices, y renderSlice().

drawSlices : bool

Esta propiedad indica si los cortes especificados se dibujan en lugar del volumen completo.

Si el valor de esta propiedad es true, se dibujarán los cortes indicados por las propiedades de índice de corte en lugar del volumen completo. Si es false, siempre se dibujará el volumen completo. Por defecto es false.

Nota: Los cortes siempre se dibujan a lo largo de los ejes del ítem, por lo que si el ítem se rota, los cortes también se rotan.

Funciones de acceso:

bool drawSlices() const
void setDrawSlices(bool enable)

Señal del notificador:

void drawSlicesChanged(bool enabled)

Véase también sliceIndexX, sliceIndexY, y sliceIndexZ.

preserveOpacity : bool

Esta propiedad mantiene si el multiplicador alfa se aplica a todos los texels.

Si el valor de esta propiedad es true, alphaMultiplier sólo se aplica a los texels que ya tienen alguna transparencia. Si es false, el multiplicador se aplica al valor alfa de todos los texels. Por defecto es true.

Funciones de acceso:

bool preserveOpacity() const
void setPreserveOpacity(bool enable)

Señal notificadora:

void preserveOpacityChanged(bool enabled)

Véase también alphaMultiplier.

sliceFrameColor : QColor

Esta propiedad contiene el color del marco de corte.

No se admite el color transparente.

Por defecto es negro.

Funciones de acceso:

QColor sliceFrameColor() const
void setSliceFrameColor(QColor color)

Señal notificadora:

void sliceFrameColorChanged(QColor color)

Véase también drawSliceFrames.

sliceFrameGaps : QVector3D

Esta propiedad mantiene el tamaño del espacio de aire que queda entre el propio volumen y el marco en cada dimensión.

El espacio puede ser diferente en distintas dimensiones. Los valores son fracciones del espesor del volumen en la misma dimensión. Los valores no pueden ser negativos.

El valor por defecto es QVector3D(0.01, 0.01, 0.01).

Funciones de acceso:

QVector3D sliceFrameGaps() const
void setSliceFrameGaps(QVector3D values)

Señal del notificador:

void sliceFrameGapsChanged(QVector3D values)

Véase también drawSliceFrames.

sliceFrameThicknesses : QVector3D

Esta propiedad contiene el grosor de los marcos de corte para cada dimensión.

Los valores son fracciones del grosor del volumen en la misma dimensión. Los valores no pueden ser negativos.

Por defecto es QVector3D(0.01, 0.01, 0.01).

Funciones de acceso:

QVector3D sliceFrameThicknesses() const
void setSliceFrameThicknesses(QVector3D values)

Señal notificadora:

void sliceFrameThicknessesChanged(QVector3D values)

Véase también drawSliceFrames.

sliceFrameWidths : QVector3D

Esta propiedad contiene la anchura del marco de corte.

La anchura puede ser diferente en diferentes dimensiones, por lo que puede, por ejemplo, omitir el dibujo de los marcos en ciertos lados del volumen estableciendo el valor para esa dimensión en cero. Los valores son fracciones del grosor del volumen en la misma dimensión. Los valores no pueden ser negativos.

Por defecto es QVector3D(0.01, 0.01, 0.01).

Funciones de acceso:

QVector3D sliceFrameWidths() const
void setSliceFrameWidths(QVector3D values)

Señal del notificador:

void sliceFrameWidthsChanged(QVector3D values)

Véase también drawSliceFrames.

sliceIndexX : int

Esta propiedad contiene el índice de la dimensión x en los datos de la textura indicando que corte vertical mostrar.

Establecer cualquier dimensión a negativo indica que no se dibuja ninguna rebanada o marco de rebanada para esa dimensión. Si todas las dimensiones son negativas, no se dibuja ningún corte o marco de corte y el volumen se dibuja normalmente.

Por defecto es -1.

Funciones de acceso:

int sliceIndexX() const
void setSliceIndexX(int value)

Señal notificadora:

void sliceIndexXChanged(int value)

Véase también textureData, drawSlices, y drawSliceFrames.

sliceIndexY : int

Esta propiedad contiene el índice de la dimensión y en los datos de la textura indicando que corte horizontal mostrar.

Establecer cualquier dimensión a negativo indica que no se dibuja ninguna rebanada o marco de rebanada para esa dimensión. Si todas las dimensiones son negativas, no se dibuja ningún corte o marco de corte y el volumen se dibuja normalmente.

Por defecto es -1.

Funciones de acceso:

int sliceIndexY() const
void setSliceIndexY(int value)

Señal notificadora:

void sliceIndexYChanged(int value)

Véase también textureData, drawSlices, y drawSliceFrames.

sliceIndexZ : int

Esta propiedad contiene el índice de la dimensión z en los datos de la textura indicando que corte vertical mostrar.

Establecer cualquier dimensión a negativo indica que no se dibuja ninguna rebanada o marco de rebanada para esa dimensión. Si todas las dimensiones son negativas, no se dibuja ningún corte o marco de corte y el volumen se dibuja normalmente.

Por defecto es -1.

Funciones de acceso:

int sliceIndexZ() const
void setSliceIndexZ(int value)

Señal notificadora:

void sliceIndexZChanged(int value)

Véase también textureData, drawSlices, y drawSliceFrames.

textureData : QList<uchar>*

Esta propiedad contiene la matriz con los datos de textura en el formato especificado por textureFormat.

El tamaño de esta matriz debe ser como mínimo (textureDataWidth * textureHeight * textureDepth * texture format color depth in bytes).

Una textura 3D está definida por una pila de subtexturas 2D. Cada subtextura debe tener un tamaño idéntico (textureDataWidth * textureHeight), y la profundidad de la pila está definida por la propiedad textureDepth. Los datos de cada textura 2D son idénticos a un dato QImage con el mismo formato, por lo que QImage::bits() puede utilizarse para suministrar los datos de cada subtextura.

La propiedad del nuevo array se transfiere a la instancia QCustom3DVolume. Si se establece otra matriz, se elimina la anterior. Si el mismo array se establece de nuevo, se asume que el contenido del array ha cambiado y se activa el renderizado del gráfico.

Nota: Cada línea de dimensión x de los datos debe estar alineada a 32 bits. Si textureFormat es QImage::Format_Indexed8 y el valor de textureWidth no es divisible por cuatro, puede ser necesario añadir bytes de relleno a cada línea de dimensión x de data. La función textureDataWidth() devuelve el recuento de bytes de relleno. Los bytes de relleno deben indicar un color totalmente transparente para evitar artefactos de renderizado.

Por defecto es 0.

Funciones de acceso:

QList<uchar> *textureData() const
void setTextureData(QList<uchar> *data)

Señal notificadora:

void textureDataChanged(QList<uchar> *data)

Véase también colorTable, setTextureFormat(), setSubTextureData(), y textureDataWidth().

textureDepth : int

Esta propiedad contiene la profundidad de la textura 3D que define el contenido del volumen en píxeles.

Por defecto es 0.

Nota: El valor textureData puede necesitar ser redimensionado o recreado si se cambia este valor. Por defecto es 0.

Funciones de acceso:

int textureDepth() const
void setTextureDepth(int value)

Señal del notificador:

void textureDepthChanged(int value)

Véase también textureData, textureWidth, textureHeight, y setTextureFormat().

textureHeight : int

Esta propiedad contiene la altura de la textura 3D que define el contenido del volumen en píxeles.

Por defecto es 0.

Nota: El valor textureData puede necesitar ser redimensionado o recreado si se cambia este valor. Por defecto es 0.

Funciones de acceso:

int textureHeight() const
void setTextureHeight(int value)

Señal del notificador:

void textureHeightChanged(int value)

Véase también textureData, textureWidth, textureDepth, y setTextureFormat().

textureWidth : int

Esta propiedad contiene el ancho de la textura 3D que define el contenido del volumen en píxeles.

Por defecto es 0.

Nota: El valor textureData puede necesitar ser redimensionado o recreado si se cambia este valor. Por defecto es 0.

Funciones de acceso:

int textureWidth() const
void setTextureWidth(int value)

Señal del notificador:

void textureWidthChanged(int value)

Véase también textureData, textureHeight, textureDepth, setTextureFormat(), y textureDataWidth().

useHighDefShader : bool

Esta propiedad indica si se utiliza un shader de alta o baja definición para renderizar el volumen.

Si el valor de esta propiedad es true, se utiliza un shader de alta definición. Si es false, se utiliza un shader de baja definición.

El shader de alta definición garantiza que cada texel visible de la textura del volumen es muestreado cuando el volumen es renderizado. El sombreador de baja definición sólo renderiza una aproximación del contenido del volumen, pero a una velocidad de fotogramas mucho mayor. El sombreador de baja definición no garantiza que se muestreen todos los texel de la textura del volumen, por lo que pueden producirse parpadeos si el volumen contiene rasgos finos definidos.

Nota: Este valor no afecta al nivel de detalle al renderizar los cortes del volumen.

Por defecto es true.

Funciones de acceso:

bool useHighDefShader() const
void setUseHighDefShader(bool enable)

Señal notificadora:

void useHighDefShaderChanged(bool enabled)

Véase también renderSlice().

Documentación de las funciones miembro

[explicit] QCustom3DVolume::QCustom3DVolume(QObject *parent = nullptr)

Construye un volumen 3D personalizado con la dirección parent.

[explicit] QCustom3DVolume::QCustom3DVolume(QVector3D position, QVector3D scaling, const QQuaternion &rotation, int textureWidth, int textureHeight, int textureDepth, QList<uchar> *textureData, QImage::Format textureFormat, const QList<QRgb> &colorTable, QObject *parent = nullptr)

Construye un volumen 3D personalizado con los datos position, scaling, rotation, textureWidth, textureHeight, textureDepth, textureData, textureFormat, colorTable, y parent opcional.

Véase también textureData, setTextureFormat(), y colorTable.

[override virtual noexcept] QCustom3DVolume::~QCustom3DVolume()

Elimina el volumen 3D personalizado.

QList<uchar> *QCustom3DVolume::createTextureData(const QList<QImage *> &images)

Crea una nueva matriz de datos de textura a partir de una matriz de images y la establece como textureData para este objeto de volumen. Las dimensiones de la textura también se establecen de acuerdo con las dimensiones de la imagen y del array. Todas las imágenes de la matriz deben tener el mismo tamaño. Si las imágenes no están todas en el formato QImage::Format_Indexed8, todos los datos de textura se convertirán al formato QImage::Format_ARGB32. Si las imágenes están en el formato QImage::Format_Indexed8, el valor colorTable para todo el volumen se tomará de la primera imagen.

Devuelve un puntero al array recién creado.

Véase también textureData, textureWidth, textureHeight, textureDepth, y setTextureFormat().

QImage QCustom3DVolume::renderSlice(Qt::Axis axis, int index)

Renderiza el corte especificado por index a lo largo del eje especificado por axis en una imagen. Se utiliza el formato de textura de este objeto.

Devuelve la imagen renderizada del corte, o una imagen nula si se especifica un índice no válido.

Véase también setTextureFormat().

void QCustom3DVolume::setSliceIndices(int x, int y, int z)

Una función conveniente para establecer los tres índices de rebanada (x, y, y z) a la vez.

Véase también textureData.

void QCustom3DVolume::setSubTextureData(Qt::Axis axis, int index, const QImage &image)

Establece una única subtextura 2D de la textura 3D a lo largo de la dirección axis especificada del volumen. El parámetro index especifica la subtextura a establecer. La fuente image debe estar en el formato especificado por la propiedad textureFormat si textureFormat está indexado. Si textureFormat es QImage::Format_ARGB32, la imagen se convierte a ese formato. La imagen debe tener el tamaño de la sección transversal de la textura de volumen a lo largo del eje especificado. La orientación de la imagen debe corresponder a la orientación de la imagen de corte producida por el método renderSlice() a lo largo del mismo eje.

Nota: Cada línea de dimensión x de los datos debe estar alineada a 32 bits cuando se orienta en el eje y o en el eje z. Si textureFormat es QImage::Format_Indexed8 y el valor de textureWidth no es divisible por cuatro, puede ser necesario añadir bytes de relleno a cada línea de dimensión x de la imagen para alinearla correctamente. Los bytes de relleno deben indicar un color totalmente transparente para evitar artefactos de renderizado. No se garantiza que QImage lo haga automáticamente.

Véase también textureData y renderSlice().

void QCustom3DVolume::setSubTextureData(Qt::Axis axis, int index, const uchar *data)

Establece una única subtextura 2D de la textura 3D a lo largo de la dirección axis especificada del volumen. El parámetro index especifica la subtextura a establecer. La textura data debe estar en el formato especificado por la propiedad textureFormat y tener el tamaño de la sección transversal de la textura del volumen a lo largo del eje especificado multiplicado por la profundidad de color del formato de textura en bytes. Se espera que data esté ordenado de forma similar a los datos de las imágenes producidas por el método renderSlice() a lo largo del mismo eje.

Nota: Cada línea de dimensión x de los datos debe estar alineada a 32 bits cuando se apunte al eje y o al eje z. Si textureFormat es QImage::Format_Indexed8 y el valor de textureWidth no es divisible por cuatro, puede ser necesario añadir bytes de relleno a cada línea de dimensión x de data para alinearla correctamente. Los bytes de relleno deben indicar un color totalmente transparente para evitar artefactos de renderizado.

Véase también textureData y renderSlice().

void QCustom3DVolume::setTextureDimensions(int width, int height, int depth)

Una función conveniente para establecer las tres dimensiones de la textura (width, height, y depth) a la vez.

Véase también textureData.

void QCustom3DVolume::setTextureFormat(QImage::Format format)

Establece el formato de la propiedad textureData en format. Actualmente sólo se admiten dos formatos: QImage::Format_Indexed8 y QImage::Format_ARGB32. Si se especifica un formato indexado, también debe establecerse colorTable. Por defecto es QImage::Format_ARGB32.

Véase también textureFormat(), colorTable, y textureData.

int QCustom3DVolume::textureDataWidth() const

Devuelve el ancho real de los datos de textura. Cuando el formato de la textura es QImage::Format_Indexed8, este valor es igual a textureWidth alineado a un límite de 32 bits. De lo contrario, este valor es igual a cuatro veces textureWidth.

QImage::Format QCustom3DVolume::textureFormat() const

Devuelve el formato del valor de la propiedad textureData.

Véase también setTextureFormat().

[signal] void QCustom3DVolume::textureFormatChanged(QImage::Format format)

Esta señal se emite cuando cambia la dirección format del valor textureData.

Véase también setTextureFormat().

© 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.