QOpenGLWidget Class

Descripción Detallada

QOpenGLWidget proporciona funcionalidad para mostrar gráficos OpenGL integrados en una aplicación Qt. Su uso es muy sencillo: Haz que tu clase herede de él y usa la subclase como cualquier otra QWidget, excepto que puedes elegir entre usar QPainter o los comandos de renderizado estándar de OpenGL.

QOpenGLWidget proporciona tres convenientes funciones virtuales que puedes reimplementar en tu subclase para realizar las tareas típicas de OpenGL:

• paintGL() - Renderiza la escena OpenGL. Es llamada cada vez que el widget necesita ser actualizado.
• resizeGL() - Configura la vista OpenGL, proyección, etc. Es llamado cuando el widget ha sido redimensionado (y también cuando se muestra por primera vez porque todos los widgets recién creados reciben un evento de redimensionamiento automáticamente).
• initializeGL() - Establece los recursos y el estado OpenGL. Se llama una vez antes de la primera llamada a resizeGL() o paintGL().

Si necesitas activar un repintado desde otros lugares que no sean paintGL() (un ejemplo típico es cuando se utiliza timers para animar escenas), debes llamar a la función update() del widget para programar una actualización.

El contexto de renderizado OpenGL de tu widget se actualiza cuando se llama a paintGL(), resizeGL(), o initializeGL(). Si necesitas llamar a las funciones estándar de la API OpenGL desde otros lugares (por ejemplo, en el constructor de tu widget o en tus propias funciones de pintura), debes llamar primero a makeCurrent().

Todo el renderizado se realiza en un objeto framebuffer OpenGL. makeCurrent() asegurarse de que está vinculado en el contexto. Ten esto en cuenta cuando crees y vincules objetos framebuffer adicionales en el código de renderizado en paintGL(). Nunca revincule el framebuffer con ID 0. En su lugar, llama a defaultFramebufferObject() para obtener el ID que debe ser vinculado.

QOpenGLWidget permite usar diferentes versiones y perfiles de OpenGL cuando la plataforma lo soporta. Solo establece el formato requerido via setFormat(). Ten en cuenta sin embargo que tener multiples instancias de QOpenGLWidget en la misma ventana requiere que todas usen el mismo formato, o al menos formatos que no hagan los contextos no compartibles. Para superar este problema, prefiere usar QSurfaceFormat::setDefaultFormat() en lugar de setFormat().

Técnicas de pintura

Como se ha descrito anteriormente, subclase QOpenGLWidget para renderizar contenido 3D puro de la siguiente manera:

• Reimplementar las funciones initializeGL() y resizeGL() para configurar el estado OpenGL y proporcionar una transformación de perspectiva.
• Reimplementar paintGL() para pintar la escena 3D, llamando únicamente a funciones OpenGL.

También es posible dibujar gráficos 2D sobre una subclase de QOpenGLWidget utilizando QPainter:

• En paintGL(), en lugar de emitir comandos OpenGL, construye un objeto QPainter para su uso en el widget.
• Dibuja primitivas usando QPainter's member functions.
• Todavía se pueden emitir comandos OpenGL directos. Sin embargo, debes asegurarte de que están incluidos en una llamada a beginNativePainting() y endNativePainting() del pintor.

Cuando se dibuja sólo con QPainter, también es posible pintar como se hace con los widgets normales: reimplementando paintEvent().

• Reimplemente la función paintEvent().
• Construya un objeto QPainter apuntando al widget. Pase el widget al constructor o a la función QPainter::begin().
• Dibuja las primitivas utilizando las funciones miembro de QPainter.
• Al terminar de pintar, se destruye la instancia QPainter. Alternativamente, llame a QPainter::end() explícitamente.

Llamadas a funciones OpenGL, cabeceras y QOpenGLFunctions

Cuando se realicen llamadas a funciones OpenGL, se recomienda encarecidamente evitar llamar a las funciones directamente. En su lugar, prefiera usar QOpenGLFunctions (cuando haga aplicaciones portables) o las variantes versionadas (por ejemplo, QOpenGLFunctions_3_2_Core y similares, cuando se dirija a OpenGL moderno, sólo para escritorio). De esta forma, la aplicación funcionará correctamente en todas las configuraciones de compilación de Qt, incluyendo las que realizan la carga dinámica de la implementación de OpenGL, lo que significa que las aplicaciones no están enlazadas directamente a una implementación de GL y, por tanto, las llamadas directas a funciones no son factibles.

En paintGL() siempre se puede acceder al contexto actual llamando a QOpenGLContext::currentContext(). Desde este contexto se puede recuperar una instancia de QOpenGLFunctions ya inicializada y lista para ser utilizada llamando a QOpenGLContext::functions(). Una alternativa a anteponer prefijos a cada llamada GL es heredar de QOpenGLFunctions y llamar a QOpenGLFunctions::initializeOpenGLFunctions() en initializeGL().

En cuanto a las cabeceras OpenGL, ten en cuenta que en la mayoría de los casos no habrá necesidad de incluir directamente ninguna cabecera como GL.h. Las cabeceras Qt relacionadas con OpenGL incluirán qopengl.h, que a su vez incluirá una cabecera apropiada para el sistema. Puede ser una cabecera OpenGL ES 3.x o 2.0, la versión más alta disponible, o una cabecera gl.h proporcionada por el sistema. Además, se proporciona una copia de las cabeceras de extensión (llamadas glext.h en algunos sistemas) como parte de Qt tanto para OpenGL como para OpenGL ES. Éstas se incluirán automáticamente en las plataformas en las que sea posible. Esto significa que las constantes y punteros de función de las extensiones ARB, EXT, OES están automáticamente disponibles.

Ejemplos de código

Para empezar, la subclase más simple de QOpenGLWidget podría ser como la siguiente:

class MyGLWidget : public QOpenGLWidget
{
public:
    MyGLWidget(QWidget *parent) : QOpenGLWidget(parent) { }

protected:
    void initializeGL() override
    {
        // Set up the rendering context, load shaders and other resources, etc.:
        QOpenGLFunctions *f = QOpenGLContext::currentContext()->functions();
        f->glClearColor(1.0f, 1.0f, 1.0f, 1.0f);
        ...
    }

    void resizeGL(int w, int h) override
    {
        // Update projection matrix and other size related settings:
        m_projection.setToIdentity();
        m_projection.perspective(45.0f, w / float(h), 0.01f, 100.0f);
        ...
    }

    void paintGL() override
    {
        // Draw the scene:
        QOpenGLFunctions *f = QOpenGLContext::currentContext()->functions();
        f->glClear(GL_COLOR_BUFFER_BIT);
        ...
    }

};

Alternativamente, el prefijo de todas y cada una de las llamadas OpenGL puede ser evitado derivando de QOpenGLFunctions en su lugar:

class MyGLWidget : public QOpenGLWidget, protected QOpenGLFunctions
{
    ...
    void initializeGL() override
    {
        initializeOpenGLFunctions();
        glClearColor(...);
        ...
    }
    ...
};

Para obtener un contexto compatible con una determinada versión o perfil de OpenGL, o para solicitar buffers de profundidad y stencil, llama a setFormat():

QOpenGLWidget *widget = new QOpenGLWidget(parent);
QSurfaceFormat format;
format.setDepthBufferSize(24);
format.setStencilBufferSize(8);
format.setVersion(3, 2);
format.setProfile(QSurfaceFormat::CoreProfile);
widget->setFormat(format); // must be called before the widget or its parent window gets shown

En contextos OpenGL 3.0+, cuando la portabilidad no es importante, las variantes versionadas de QOpenGLFunctions permiten acceder fácilmente a todas las funciones OpenGL modernas disponibles en una versión determinada:

    ...
    void paintGL() override
    {
        QOpenGLFunctions_3_2_Core *f = QOpenGLContext::currentContext()->versionFunctions<QOpenGLFunctions_3_2_Core>();
        ...
        f->glDrawArraysInstanced(...);
        ...
    }
    ...

Como se ha descrito anteriormente, es más sencillo y robusto establecer el formato solicitado de forma global para que se aplique a todas las ventanas y contextos durante el tiempo de vida de la aplicación. A continuación se muestra un ejemplo de ello:

int main(int argc, char **argv)
{
    QApplication app(argc, argv);

    QSurfaceFormat format;
    format.setDepthBufferSize(24);
    format.setStencilBufferSize(8);
    format.setVersion(3, 2);
    format.setProfile(QSurfaceFormat::CoreProfile);
    QSurfaceFormat::setDefaultFormat(format);

    MyWidget widget;
    widget.show();

    return app.exec();
}

Muestreo múltiple

Para habilitar el multimuestreo, establezca el número de muestras solicitadas en la dirección QSurfaceFormat que se pasa a setFormat(). En sistemas que no lo soporten la petición puede ser ignorada.

El soporte de multimuestreo requiere soporte para renderbuffers multimuestreo y framebuffer blits. En las implementaciones de OpenGL ES 2.0 es probable que no estén presentes. Esto significa que el multimuestreo no estará disponible. Con las versiones modernas de OpenGL y OpenGL ES 3.0 y superiores esto ya no suele ser un problema.

Threading

Realizar renderizado fuera de pantalla en hilos de trabajo, por ejemplo para generar texturas que luego se usan en el hilo GUI/principal en paintGL(), está soportado exponiendo el QOpenGLContext del widget para que se puedan crear contextos adicionales que compartan con él en cada hilo.

Dibujar directamente al framebuffer de QOpenGLWidget fuera del hilo GUI/main es posible reimplementando paintEvent() para no hacer nada. La afinidad de hilo del contexto tiene que ser cambiada a través de QObject::moveToThread(). Después de eso, makeCurrent() y doneCurrent() son utilizables en el hilo trabajador. Ten cuidado de volver a mover el contexto al hilo GUI/principal después.

Activar un cambio de buffer solo para el QOpenGLWidget no es posible ya que no hay una superficie nativa real en pantalla para el. Depende de la pila del widget gestionar la composición y los cambios de buffer en el hilo gui. Cuando un hilo termina de actualizar el framebuffer, llama a update() en el hilo GUI/principal para programar la composición.

Hay que tener especial cuidado para evitar el uso del framebuffer cuando el hilo GUI/principal está realizando la composición. Las señales aboutToCompose() y frameSwapped() serán emitidas cuando la composición comience y termine. Se emiten en el hilo GUI/main. Esto significa que utilizando una conexión directa aboutToCompose() puede bloquear el hilo GUI/main hasta que el hilo worker haya terminado su renderizado. Después de eso, el hilo trabajador no debe realizar más renderizado hasta que la señal frameSwapped() sea emitida. Si esto no es aceptable, el subproceso trabajador debe implementar un mecanismo de doble buffering. Esto implica dibujar usando un objetivo de render alternativo, que es totalmente controlado por el hilo, por ejemplo, un objeto framebuffer adicional, y blitting al framebuffer del QOpenGLWidget en un momento adecuado.

Contexto Compartido

Cuando múltiples QOpenGLWidgets son añadidos como hijos al mismo widget de nivel superior, sus contextos se compartirán entre ellos. Esto no aplica para instancias QOpenGLWidget que pertenecen a diferentes ventanas.

Esto significa que todos los QOpenGLWidgets en la misma ventana pueden acceder a los recursos compartidos de los otros, como texturas, y no hay necesidad de un contexto "global compartido" extra.

Para configurar el uso compartido entre instancias de QOpenGLWidget pertenecientes a diferentes ventanas, establece el atributo de aplicación Qt::AA_ShareOpenGLContexts antes de instanciar QApplication. Esto activará la compartición entre todas las instancias de QOpenGLWidget sin ningún otro paso.

Crear instancias extra de QOpenGLContext que compartan recursos como texturas con el contexto de QOpenGLWidget también es posible. Simplemente pasa el puntero devuelto por context() a QOpenGLContext::setShareContext() antes de llamar a QOpenGLContext::create(). El contexto resultante tambien puede ser usado en un hilo diferente, permitiendo la generacion de texturas en hilos y la carga asincronica de texturas.

Ten en cuenta que QOpenGLWidget espera una implementacion estandar de comparticion de recursos cuando se trata de los drivers graficos subyacentes. Por ejemplo, algunos controladores, en particular para móviles y hardware embebido, tienen problemas con la configuración de la compartición entre un contexto existente y otros que se crean más tarde. Otros controladores pueden comportarse de forma inesperada al intentar utilizar recursos compartidos entre diferentes subprocesos.

Inicialización y limpieza de recursos

Se garantiza que el contexto OpenGL asociado al QOpenGLWidget es actual siempre que se invoque a initializeGL() y paintGL(). No intentes crear recursos OpenGL antes de que initializeGL() sea invocado. Por ejemplo, intentar compilar shaders, inicializar objetos vertex buffer o cargar datos de textura fallará si se hace en el constructor de una subclase. Estas operaciones deben ser diferidas a initializeGL(). Algunas de las clases de ayuda OpenGL de Qt, como QOpenGLBuffer o QOpenGLVertexArrayObject, tienen un comportamiento diferido similar: pueden ser instanciadas sin un contexto, pero toda la inicialización es diferida hasta una llamada a create(), o similar. Esto significa que pueden ser usadas como variables miembro normales (no puntero) en una subclase QOpenGLWidget, pero la funcion create() o similar solo puede ser llamada desde initializeGL(). Ten en cuenta que no todas las clases estan diseñadas asi. En caso de duda, haz que la variable miembro sea un puntero y crea y destruye la instancia dinamicamente en initializeGL() y el destructor, respectivamente.

Liberar los recursos también necesita que el contexto sea actual. Por lo tanto, se espera que los destructores que realizan dicha limpieza llamen a makeCurrent() antes de pasar a destruir cualquier recurso o envoltorio de OpenGL. Evite el borrado diferido a través de deleteLater() o el mecanismo parenting de QObject. No hay garantía de que el contexto correcto sea actual en el momento en que la instancia en cuestión es realmente destruida.

Por lo tanto, una subclase típica tendrá a menudo el siguiente aspecto en lo que respecta a la inicialización y destrucción de recursos:

class MyGLWidget : public QOpenGLWidget
{
    ...

private:
    QOpenGLVertexArrayObject m_vao;
    QOpenGLBuffer m_vbo;
    QOpenGLShaderProgram *m_program;
    QOpenGLShader *m_shader;
    QOpenGLTexture *m_texture;
};

MyGLWidget::MyGLWidget()
    : m_program(0), m_shader(0), m_texture(0)
{
    // No OpenGL resource initialization is done here.
}

MyGLWidget::~MyGLWidget()
{
    // Make sure the context is current and then explicitly
    // destroy all underlying OpenGL resources.
    makeCurrent();

    delete m_texture;
    delete m_shader;
    delete m_program;

    m_vbo.destroy();
    m_vao.destroy();

    doneCurrent();
}

void MyGLWidget::initializeGL()
{
    m_vao.create();
    if (m_vao.isCreated())
        m_vao.bind();

    m_vbo.create();
    m_vbo.bind();
    m_vbo.allocate(...);

    m_texture = new QOpenGLTexture(QImage(...));

    m_shader = new QOpenGLShader(...);
    m_program = new QOpenGLShaderProgram(...);

    ...
}

Esto funciona para la mayoría de los casos, pero no es del todo ideal como solución genérica. Cuando el widget es reparentado de forma que termina en una ventana de nivel superior completamente diferente, se necesita algo más: conectándose a la señal aboutToBeDestroyed() de QOpenGLContext, se puede realizar una limpieza siempre que el contexto OpenGL esté a punto de ser liberado.

MyGLWidget::~MyGLWidget()
{
    cleanup();
}

void MyGLWidget::initializeGL()
{
    ...
    connect(context(), &QOpenGLContext::aboutToBeDestroyed, this, &MyGLWidget::cleanup);
}

void MyGLWidget::cleanup()
{
    makeCurrent();
    delete m_texture;
    m_texture = 0;
    ...
    doneCurrent();
    disconnect(context(), &QOpenGLContext::aboutToBeDestroyed, this, &MyGLWidget::cleanup);
}

Una limpieza adecuada es especialmente importante debido a la compartición de contextos. Aunque el contexto asociado a cada QOpenGLWidget es destruido junto con el QOpenGLWidget, los recursos compartidos en ese contexto, como texturas, permaneceran validos hasta que la ventana de nivel superior, en la que vivia el QOpenGLWidget, sea destruida. Adicionalmente, configuraciones como Qt::AA_ShareOpenGLContexts y algunos módulos Qt pueden activar un alcance aún mayor para compartir contextos, llevando potencialmente a mantener vivos los recursos en cuestión durante todo el tiempo de vida de la aplicación. Por lo tanto lo mas seguro y robusto es siempre realizar una limpieza explicita para todos los recursos y envoltorios de recursos usados en el QOpenGLWidget.

Limitaciones y otras consideraciones

Poner otros widgets debajo y hacer el QOpenGLWidget transparente no llevara a los resultados esperados: Los widgets debajo no serán visibles. Esto se debe a que en la practica el QOpenGLWidget se dibuja antes que el resto de widgets normales, no-OpenGL, y por tanto las soluciones transparentes no son factibles. Otro tipo de diseños, como tener widgets encima del QOpenGLWidget, funcionaran como se espera.

Cuando sea absolutamente necesario, esta limitacion puede ser superada estableciendo el atributo Qt::WA_AlwaysStackOnTop en el QOpenGLWidget. Ten en cuenta sin embargo que esto rompe el orden de apilamiento, por ejemplo no sera posible tener otros widgets encima del QOpenGLWidget, asi que solo deberia usarse en situaciones donde se requiera un QOpenGLWidget semitransparente con otros widgets visibles debajo.

Nótese que esto no se aplica cuando no hay otros widgets debajo y la intención es tener una ventana semitransparente. En ese caso, el enfoque tradicional de establecer Qt::WA_TranslucentBackground en la ventana de nivel superior es suficiente. Ten en cuenta que si las areas transparentes solo se desean en el QOpenGLWidget, entonces Qt::WA_NoSystemBackground necesitara volver a false despues de habilitar Qt::WA_TranslucentBackground. Adicionalmente, solicitar un canal alfa para el contexto de QOpenGLWidget via setFormat() puede ser necesario tambien, dependiendo del sistema.

QOpenGLWidget soporta múltiples comportamientos de actualización, al igual que QOpenGLWindow. En modo preservado el contenido renderizado de la anterior llamada a paintGL() esta disponible en la siguiente, permitiendo un renderizado incremental. En modo no preservado el contenido se pierde y se espera que las implementaciones de paintGL() redibujen todo en la vista.

Antes de Qt 5.5 el comportamiento por defecto de QOpenGLWidget era preservar el contenido renderizado entre llamadas a paintGL(). Desde Qt 5.5 el comportamiento por defecto es no preservar porque esto proporciona un mejor rendimiento y la mayoría de las aplicaciones no necesitan el contenido previo. Esto también se asemeja a la semántica de un QWindow basado en OpenGL y coincide con el comportamiento por defecto de QOpenGLWindow en que el color y los buffers auxiliares se invalidan para cada fotograma. Para restaurar el comportamiento conservado, llame a setUpdateBehavior() con PartialUpdate.

Una vez que se añade un QOpenGLWidget a una jerarquía de widgets, el contenido de la ventana de nivel superior se descarga mediante renderizado basado en OpenGL. Los widgets distintos al QOpenGLWidget continúan dibujando su contenido usando un pintor basado en software, pero la composición final se realiza a través de la API 3D.

Alternativas

Añadir un QOpenGLWidget en una ventana activa la composición basada en OpenGL para toda la ventana. En algunos casos especiales esto puede no ser lo ideal, y se desea el viejo comportamiento estilo QGLWidget con una ventana hija separada y nativa. Las aplicaciones de escritorio que entienden las limitaciones de este enfoque (por ejemplo cuando se trata de superposiciones, transparencia, vistas de desplazamiento y áreas MDI), pueden utilizar QOpenGLWindow con QWidget::createWindowContainer(). Esta es una alternativa moderna a QGLWidget y es más rápida que QOpenGLWidget debido a la ausencia del paso adicional de composición. Se recomienda encarecidamente limitar el uso de este enfoque a los casos en que no hay otra opción. Tenga en cuenta que esta opción no es adecuada para la mayoría de las plataformas embebidas y móviles, y se sabe que también tiene problemas en ciertas plataformas de escritorio (por ejemplo, macOS). La solución estable y multiplataforma es siempre QOpenGLWidget.

Renderizado estereoscópico

A partir de la versión 6.5 QOpenGLWidget tiene soporte para renderizado estereoscópico. Para habilitarlo, establece la bandera QSurfaceFormat::StereoBuffers globalmente antes de crear la ventana, usando QSurfaceFormat::SetDefaultFormat().

Esto hará que paintGL() sea llamado dos veces cada frame, una vez por cada QOpenGLWidget::TargetBuffer. En paintGL(), llame a currentTargetBuffer() para consultar a cuál se está dibujando actualmente.

OpenGL es una marca registrada de Silicon Graphics, Inc. en Estados Unidos y otros países.