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) |
Elementos no miembros relacionados
| 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`.
| Constante | Valor | Descripción |
|---|---|---|
QSurfaceFormat::StereoBuffers | 0x0001 | Se utiliza para solicitar búferes estéreo en el formato de superficie. |
QSurfaceFormat::DebugContext | 0x0002 | Se utiliza para solicitar un contexto de depuración con información adicional de depuración. |
QSurfaceFormat::DeprecatedFunctions | 0x0004 | Se 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::ResetNotification | 0x0008 | Habilita 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::ProtectedContent | 0x0010 | Habilita 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`.
| Constante | Valor | Descripción |
|---|---|---|
QSurfaceFormat::NoProfile | 0 | La versión de OpenGL es inferior a 3.2. Para la versión 3.2 y posteriores, es lo mismo que CoreProfile. |
QSurfaceFormat::CoreProfile | 1 | La funcionalidad obsoleta en la versión 3.0 de OpenGL no está disponible. |
QSurfaceFormat::CompatibilityProfile | 2 | Las funcionalidades de versiones anteriores de OpenGL están disponibles. |
enum QSurfaceFormat::RenderableType
Esta enumeración especifica el motor de renderizado de la superficie.
| Constante | Valor | Descripción |
|---|---|---|
QSurfaceFormat::DefaultRenderableType | 0x0 | El método de renderizado predeterminado, no especificado |
QSurfaceFormat::OpenGL | 0x1 | Renderizado OpenGL de escritorio |
QSurfaceFormat::OpenGLES | 0x2 | Representación con OpenGL ES 2.0 |
QSurfaceFormat::OpenVG | 0x4 | Renderizado 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.
| Constante | Valor | Descripción |
|---|---|---|
QSurfaceFormat::DefaultSwapBehavior | 0 | El comportamiento de intercambio predeterminado y no especificado de la plataforma. |
QSurfaceFormat::SingleBuffer | 1 | Se 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::DoubleBuffer | 2 | Este 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::TripleBuffer | 3 | Este 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.