En esta página

QSurfaceFormat Class

La clase QSurfaceFormat representa el formato de una superficie de trabajo ( QSurface). Más información...

Encabezado: #include <QSurfaceFormat>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui

Tipos públicos

enum FormatOption { StereoBuffers, DebugContext, DeprecatedFunctions, ResetNotification, ProtectedContent }
flags FormatOptions
enum OpenGLContextProfile { NoProfile, CoreProfile, CompatibilityProfile }
enum RenderableType { DefaultRenderableType, OpenGL, OpenGLES, OpenVG }
enum SwapBehavior { DefaultSwapBehavior, SingleBuffer, DoubleBuffer, TripleBuffer }

Funciones públicas

QSurfaceFormat()
QSurfaceFormat(QSurfaceFormat::FormatOptions options)
QSurfaceFormat(const QSurfaceFormat &other)
~QSurfaceFormat()
int alphaBufferSize() const
int blueBufferSize() const
const QColorSpace &colorSpace() const
int depthBufferSize() const
int greenBufferSize() const
bool hasAlpha() const
int majorVersion() const
int minorVersion() const
QSurfaceFormat::FormatOptions options() const
QSurfaceFormat::OpenGLContextProfile profile() const
int redBufferSize() const
QSurfaceFormat::RenderableType renderableType() const
int samples() const
void setAlphaBufferSize(int size)
void setBlueBufferSize(int size)
(since 6.0) void setColorSpace(const QColorSpace &colorSpace)
void setDepthBufferSize(int size)
void setGreenBufferSize(int size)
void setMajorVersion(int major)
void setMinorVersion(int minor)
void setOption(QSurfaceFormat::FormatOption option, bool on = true)
void setOptions(QSurfaceFormat::FormatOptions options)
void setProfile(QSurfaceFormat::OpenGLContextProfile profile)
void setRedBufferSize(int size)
void setRenderableType(QSurfaceFormat::RenderableType type)
void setSamples(int numSamples)
void setStencilBufferSize(int size)
void setStereo(bool enable)
void setSwapBehavior(QSurfaceFormat::SwapBehavior behavior)
void setSwapInterval(int interval)
void setVersion(int major, int minor)
int stencilBufferSize() const
bool stereo() const
QSurfaceFormat::SwapBehavior swapBehavior() const
int swapInterval() const
bool testOption(QSurfaceFormat::FormatOption option) const
std::pair<int, int> version() const
QSurfaceFormat &operator=(const QSurfaceFormat &other)

Miembros públicos estáticos

QSurfaceFormat defaultFormat()
void setDefaultFormat(const QSurfaceFormat &format)
bool operator!=(const QSurfaceFormat &lhs, const QSurfaceFormat &rhs)
bool operator==(const QSurfaceFormat &lhs, const QSurfaceFormat &rhs)

Descripción detallada

El formato incluye el tamaño de los búferes de color (rojo, verde y azul); el tamaño del búfer alfa; el tamaño de los búferes de profundidad y de plantilla; y el número de muestras por píxel para el multimuestreo. Además, el formato contiene parámetros de configuración de la superficie, como el perfil y la versión de OpenGL para el renderizado, si se deben habilitar o no los búferes estéreo y el comportamiento del intercambio.

Nota: A la hora de solucionar problemas relacionados con el contexto o el formato de ventana, puede resultar útil habilitar la categoría de registro « qt.qpa.gl ». Dependiendo de la plataforma, esto puede mostrar información de depuración útil en lo que respecta a la inicialización de OpenGL y a las configuraciones nativas de visualización o del búfer de fotogramas a las que se asigna QSurfaceFormat.

Documentación sobre los tipos de miembros

enum QSurfaceFormat::FormatOption
flags QSurfaceFormat::FormatOptions

Esta enumeración contiene opciones de formato para utilizar con ` QSurfaceFormat`.

ConstanteValorDescripción
QSurfaceFormat::StereoBuffers0x0001Se utiliza para solicitar búferes estéreo en el formato de superficie.
QSurfaceFormat::DebugContext0x0002Se utiliza para solicitar un contexto de depuración con información adicional de depuración.
QSurfaceFormat::DeprecatedFunctions0x0004Se utiliza para solicitar que se incluyan funciones obsoletas en el perfil del contexto de OpenGL. Si no se especifica, se debería obtener un contexto compatible con versiones futuras sin las funcionalidades marcadas como obsoletas. Esto requiere la versión 3.0 o superior de OpenGL.
QSurfaceFormat::ResetNotification0x0008Habilita las notificaciones sobre reinicios del contexto de OpenGL. El estado se puede consultar mediante la función isValid() del contexto. Ten en cuenta que no establecer este indicador no garantiza que nunca se produzca una pérdida del estado del contexto. Además, algunas implementaciones pueden optar por informar de la pérdida del contexto independientemente de este indicador. Las plataformas que admiten la activación dinámica de la supervisión de la pérdida de contexto, como Windows con WGL o Linux/X11 (xcb) con GLX, supervisarán el estado en cada llamada a ` makeCurrent()`. Consulte ` isValid()` para obtener más información al respecto.
QSurfaceFormat::ProtectedContent0x0010Habilita el acceso a contenido protegido. Esto permite a la GPU operar con recursos protegidos (superficies, búferes, texturas), por ejemplo, contenido de vídeo protegido por DRM. Actualmente solo está implementado para EGL.

El tipo `FormatOptions` es una definición de tipo (`typedef`) para ` QFlags<FormatOption>`. Almacena una combinación OR de valores de `FormatOption`.

enum QSurfaceFormat::OpenGLContextProfile

Esta enumeración se utiliza para especificar el perfil del contexto de OpenGL, junto con las funciones ` QSurfaceFormat::setMajorVersion()` y ` QSurfaceFormat::setMinorVersion()`.

Los perfiles están disponibles en OpenGL 3.2 y versiones posteriores, y se utilizan para elegir entre un perfil básico restringido y un perfil de compatibilidad que puede contener funcionalidades de soporte obsoletas.

Ten en cuenta que el perfil básico aún puede contener funcionalidades obsoletas y cuya eliminación está prevista en una versión posterior. Para acceder a las funcionalidades obsoletas del perfil básico en la versión de OpenGL establecida, puedes utilizar la opción de formato de ` QSurfaceFormat `: ` QSurfaceFormat::DeprecatedFunctions`.

ConstanteValorDescripción
QSurfaceFormat::NoProfile0La versión de OpenGL es inferior a 3.2. Para la versión 3.2 y posteriores, es lo mismo que CoreProfile.
QSurfaceFormat::CoreProfile1La funcionalidad obsoleta en la versión 3.0 de OpenGL no está disponible.
QSurfaceFormat::CompatibilityProfile2Las funcionalidades de versiones anteriores de OpenGL están disponibles.

enum QSurfaceFormat::RenderableType

Esta enumeración especifica el motor de renderizado de la superficie.

ConstanteValorDescripción
QSurfaceFormat::DefaultRenderableType0x0El método de renderizado predeterminado, no especificado
QSurfaceFormat::OpenGL0x1Renderizado OpenGL de escritorio
QSurfaceFormat::OpenGLES0x2Representación con OpenGL ES 2.0
QSurfaceFormat::OpenVG0x4Renderizado con Open Vector Graphics

enum QSurfaceFormat::SwapBehavior

QSurfaceFormat utiliza esta enumeración para especificar el comportamiento de intercambio de una superficie. El comportamiento de intercambio es, en gran medida, transparente para la aplicación, pero afecta a factores como la latencia de renderizado y el rendimiento.

ConstanteValorDescripción
QSurfaceFormat::DefaultSwapBehavior0El comportamiento de intercambio predeterminado y no especificado de la plataforma.
QSurfaceFormat::SingleBuffer1Se utiliza para solicitar un único búfer, lo que puede provocar parpadeos cuando el renderizado OpenGL se realiza directamente en pantalla sin un búfer intermedio fuera de pantalla.
QSurfaceFormat::DoubleBuffer2Este suele ser el comportamiento predeterminado de intercambio en plataformas de escritorio, y consiste en un búfer trasero y un búfer delantero. El renderizado se realiza en el búfer trasero y, a continuación, se intercambian el búfer trasero y el delantero, o se copia el contenido del búfer trasero al delantero, dependiendo de la implementación.
QSurfaceFormat::TripleBuffer3Este comportamiento de intercambio se utiliza a veces para reducir el riesgo de que se salte un fotograma cuando la velocidad de renderizado apenas alcanza a seguir el ritmo de la frecuencia de actualización de la pantalla. Dependiendo de la plataforma, también podría dar lugar a un uso ligeramente más eficiente de la GPU debido a un mejor comportamiento del pipelining. El triple búfer conlleva el coste de un fotograma adicional de uso de memoria y latencia, y es posible que no sea compatible dependiendo de la plataforma subyacente.

Documentación de las funciones miembro

QSurfaceFormat::QSurfaceFormat()

Crea un objeto `QSurfaceFormat` inicializado de forma predeterminada.

Nota: Por defecto, se requiere OpenGL 2.0, ya que ofrece el mayor grado de portabilidad entre plataformas e implementaciones de OpenGL.

QSurfaceFormat::QSurfaceFormat(QSurfaceFormat::FormatOptions options)

Crea un objeto `QSurfaceFormat` con el formato indicado: ` options`.

QSurfaceFormat::QSurfaceFormat(const QSurfaceFormat &other)

Crea una copia de other.

[noexcept] QSurfaceFormat::~QSurfaceFormat()

Destruye el « QSurfaceFormat ».

int QSurfaceFormat::alphaBufferSize() const

Obtiene el tamaño, en bits, del canal alfa del búfer de color.

Véase también setAlphaBufferSize().

int QSurfaceFormat::blueBufferSize() const

Obtiene el tamaño, en bits, del canal azul del búfer de color.

Véase también setBlueBufferSize().

const QColorSpace &QSurfaceFormat::colorSpace() const

Devuelve el espacio de color.

Véase también setColorSpace().

[static] QSurfaceFormat QSurfaceFormat::defaultFormat()

Devuelve el formato de superficie predeterminado global.

Cuando no se llama a ` setDefaultFormat()``, se trata de un objeto ` QSurfaceFormat` creado con el constructor por defecto.

Véase también setDefaultFormat().

int QSurfaceFormat::depthBufferSize() const

Devuelve el tamaño del búfer de profundidad.

Véase también setDepthBufferSize().

int QSurfaceFormat::greenBufferSize() const

Obtiene el tamaño, en bits, del canal verde del búfer de color.

Véase también setGreenBufferSize().

bool QSurfaceFormat::hasAlpha() const

Devuelve « true » si el tamaño del búfer alfa es mayor que cero.

Esto significa que la superficie podría utilizarse con efectos de translucidez por píxel.

int QSurfaceFormat::majorVersion() const

Devuelve la versión principal de OpenGL.

La versión por defecto es la 2.0.

Véase también setMajorVersion().

int QSurfaceFormat::minorVersion() const

Devuelve la versión secundaria de OpenGL.

Véase también setMinorVersion().

QSurfaceFormat::FormatOptions QSurfaceFormat::options() const

Devuelve las opciones de formato establecidas actualmente.

Véase también setOption(), setOptions() y testOption().

QSurfaceFormat::OpenGLContextProfile QSurfaceFormat::profile() const

Obtiene el perfil del contexto OpenGL configurado.

Esta configuración se ignora si la versión de OpenGL solicitada es inferior a 3.2.

Véase también setProfile().

int QSurfaceFormat::redBufferSize() const

Obtiene el tamaño, en bits, del canal rojo del búfer de color.

Véase también setRedBufferSize().

QSurfaceFormat::RenderableType QSurfaceFormat::renderableType() const

Obtiene el tipo renderizable.

Elige entre OpenGL de escritorio, OpenGL ES y OpenVG.

Véase también setRenderableType().

int QSurfaceFormat::samples() const

Devuelve el número de muestras por píxel cuando el multimuestreo está activado, o « -1 » cuando está desactivado. El valor de retorno por defecto es « -1 ».

Véase también setSamples().

void QSurfaceFormat::setAlphaBufferSize(int size)

Establece el valor deseado de « size » en bits del canal alfa del búfer de color.

Véase también alphaBufferSize().

void QSurfaceFormat::setBlueBufferSize(int size)

Establece el valor deseado de « size » en bits del canal azul del búfer de color.

Véase también blueBufferSize().

[since 6.0] void QSurfaceFormat::setColorSpace(const QColorSpace &colorSpace)

Establece el « colorSpace » preferido.

Por ejemplo, esto permite solicitar ventanas con framebuffers predeterminados compatibles con sRGB en plataformas que lo admitan.

Nota: Cuando la plataforma no admite el espacio de color solicitado, la solicitud se ignora. Consulta el QSurfaceFormat tras la creación de la ventana para comprobar si se ha podido satisfacer la solicitud de espacio de color o no.

Nota: Esta configuración controla si el framebuffer predeterminado de la ventana es capaz de realizar actualizaciones y mezclas en un espacio de color determinado. Por sí sola, no modifica la salida de las aplicaciones. El código de renderizado de las aplicaciones seguirá teniendo que habilitarlo mediante las llamadas OpenGL adecuadas para permitir que las actualizaciones y mezclas se realicen en el espacio de color dado, en lugar de utilizar las operaciones lineales estándar.

Esta función se introdujo en Qt 6.0.

Véase también colorSpace().

[static] void QSurfaceFormat::setDefaultFormat(const QSurfaceFormat &format)

Establece la superficie predeterminada global format.

Este formato se utiliza por defecto en QOpenGLContext, QWindow, QOpenGLWidget y clases similares.

Siempre se puede anular para cada instancia utilizando la función setFormat() propia de la clase en cuestión. Sin embargo, suele ser más conveniente establecer el formato para todas las ventanas una sola vez al inicio de la aplicación. Además, garantiza un comportamiento adecuado en los casos en los que se requieren contextos compartidos, ya que establecer el formato mediante esta función garantiza que todos los contextos y superficies, incluso los creados internamente por Qt, utilicen el mismo formato.

Véase también defaultFormat().

void QSurfaceFormat::setDepthBufferSize(int size)

Establece el tamaño mínimo del búfer de profundidad en size.

Véase también depthBufferSize().

void QSurfaceFormat::setGreenBufferSize(int size)

Establece el valor deseado de « size » en bits del canal verde del búfer de color.

Véase también greenBufferSize().

void QSurfaceFormat::setMajorVersion(int major)

Establece la versión deseada de OpenGL de major.

Véase también majorVersion().

void QSurfaceFormat::setMinorVersion(int minor)

Establece la versión deseada de OpenGL de « minor ».

La versión predeterminada es la 2.0.

Véase también minorVersion().

void QSurfaceFormat::setOption(QSurfaceFormat::FormatOption option, bool on = true)

Establece la opción de formato « option » si « on » es verdadero; en caso contrario, desactiva la opción.

Para comprobar que se ha respetado una opción, compara el formato real con el formato solicitado tras la creación de la superficie o el contexto.

Véase también setOptions(), options() y testOption().

void QSurfaceFormat::setOptions(QSurfaceFormat::FormatOptions options)

Establece las opciones de formato en « options ».

Para comprobar que se ha respetado una opción, compara el formato real con el formato solicitado tras la creación de la superficie o el contexto.

Véase también options() y testOption().

void QSurfaceFormat::setProfile(QSurfaceFormat::OpenGLContextProfile profile)

Establece el contexto OpenGL deseado profile.

Esta configuración se ignora si la versión de OpenGL solicitada es inferior a 3.2.

Véase también profile().

void QSurfaceFormat::setRedBufferSize(int size)

Establece el valor deseado de « size » en bits del canal rojo del búfer de color.

Véase también redBufferSize().

void QSurfaceFormat::setRenderableType(QSurfaceFormat::RenderableType type)

Establece el « type » que se desea renderizar.

Elige entre OpenGL de escritorio, OpenGL ES y OpenVG.

Véase también renderableType().

void QSurfaceFormat::setSamples(int numSamples)

Establece el número deseado de muestras por píxel cuando el multimuestreo está activado en numSamples. Por defecto, el multimuestreo está desactivado.

Véase también ` samples()`.

void QSurfaceFormat::setStencilBufferSize(int size)

Establece el tamaño preferido del búfer de plantillas en size bits.

Véase también ` stencilBufferSize()`.

void QSurfaceFormat::setStereo(bool enable)

Si « enable » es «true», se activa el almacenamiento en búfer estéreo; en caso contrario, se desactiva.

El almacenamiento en búfer estéreo está desactivado por defecto.

El almacenamiento en búfer estéreo proporciona búferes de color adicionales para generar imágenes para el ojo izquierdo y el ojo derecho.

Véase también stereo().

void QSurfaceFormat::setSwapBehavior(QSurfaceFormat::SwapBehavior behavior)

Establece el comportamiento de intercambio ( behavior ) de la superficie.

El comportamiento de intercambio especifica si se desea un búfer simple, doble o triple. El valor por defecto, DefaultSwapBehavior, proporciona el comportamiento de intercambio predeterminado de la plataforma.

Véase también swapBehavior().

void QSurfaceFormat::setSwapInterval(int interval)

Establece el intervalo de intercambio preferido. El intervalo de intercambio especifica el número mínimo de fotogramas de vídeo que se muestran antes de que se produzca un intercambio de búfer. Esto se puede utilizar para sincronizar el dibujo GL en una ventana con la frecuencia de actualización vertical de la pantalla.

Si se establece el valor « interval » en 0, se desactivará la sincronización con la frecuencia de refresco vertical; cualquier valor superior a 0 activará dicha sincronización. Si se establece « interval » en un valor más alto, por ejemplo 10, se producirán 10 retraces verticales entre cada intercambio de búfer.

El intervalo predeterminado es 1.

Es posible que la plataforma subyacente no admita el cambio del intervalo de intercambio. En ese caso, la solicitud se ignorará sin aviso.

Véase también swapInterval().

void QSurfaceFormat::setVersion(int major, int minor)

Establece las versiones deseadas de OpenGL: major y minor.

La versión predeterminada es la 2.0.

Véase también version().

int QSurfaceFormat::stencilBufferSize() const

Devuelve el tamaño del búfer de plantilla en bits.

Véase también setStencilBufferSize().

bool QSurfaceFormat::stereo() const

Devuelve « true » si el almacenamiento en búfer estéreo está activado; en caso contrario, devuelve «false». El almacenamiento en búfer estéreo está desactivado por defecto.

Véase también setStereo().

QSurfaceFormat::SwapBehavior QSurfaceFormat::swapBehavior() const

Devuelve el comportamiento de intercambio configurado.

Véase también setSwapBehavior().

int QSurfaceFormat::swapInterval() const

Devuelve el intervalo de intercambio.

Véase también setSwapInterval().

bool QSurfaceFormat::testOption(QSurfaceFormat::FormatOption option) const

Devuelve «true» si está activada la opción de formato « option »; en caso contrario, devuelve «false».

Véase también options().

std::pair<int, int> QSurfaceFormat::version() const

Devuelve un std::pair<int, int> que representa la versión de OpenGL.

Útil para comprobar la versión; por ejemplo: format.version() >= std::pair(3, 2)

Véase también setVersion().

QSurfaceFormat &QSurfaceFormat::operator=(const QSurfaceFormat &other)

Asigna « other » a este objeto.

Elementos no miembros relacionados

[noexcept] bool operator!=(const QSurfaceFormat &lhs, const QSurfaceFormat &rhs)

Devuelve « false » si todas las opciones de los dos objetos « QSurfaceFormat » — lhs y rhs — son iguales; en caso contrario, devuelve « true ».

[noexcept] bool operator==(const QSurfaceFormat &lhs, const QSurfaceFormat &rhs)

Devuelve « true » si todas las opciones de los dos objetos « QSurfaceFormat » — lhs y rhs — son iguales.

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