QOpenGLWidget Class

詳細な説明

Qt OpenGL Widgetは、Qtアプリケーションに統合されたOpenGLグラフィックスを表示するための機能を提供します。使い方は非常に簡単です。クラスをこのクラスから継承させ、他のQWidget と同様にサブクラスを使用するだけです。ただし、QPainter と標準のOpenGLレンダリングコマンドのどちらを使用するかを選択できる点が異なります。

QOpenGLWidget は、サブクラスで再実装して一般的な OpenGL タスクを実行できる、3 つの便利な仮想関数を提供しています：

• paintGL() - OpenGLシーンをレンダリングします。ウィジェットの更新が必要なたびに呼び出されます。
• resizeGL() - OpenGLのビューポートや投影設定などを設定します。ウィジェットのサイズが変更されるたびに呼び出されます（また、新しく作成されたウィジェットはすべて自動的にサイズ変更イベントを受け取るため、初めて表示される際にも呼び出されます）。
• initializeGL() - OpenGLのリソースと状態を設定します。resizeGL()またはpaintGL()が最初に呼び出される前に一度呼び出されます。

paintGL() 以外の場所から再描画をトリガーする必要がある場合（典型的な例は、timers を使用してシーンをアニメーション化する場合です）、ウィジェットのupdate() 関数を呼び出して更新をスケジュールする必要があります。

paintGL()、resizeGL()、またはinitializeGL() が呼び出されると、ウィジェットの OpenGL レンダリングコンテキストが現在のものになります。他の場所（例えば、ウィジェットのコンストラクタ内や独自のペイント関数内）から標準の OpenGL API 関数を呼び出す必要がある場合は、まずmakeCurrent() を呼び出す必要があります。

すべてのレンダリングは OpenGL フレームバッファオブジェクト内で行われます。makeCurrent() は、それがコンテキストにバインドされていることを保証します。paintGL() 内のレンダリングコードで追加のフレームバッファオブジェクトを作成およびバインドする際は、この点に留意してください。ID 0 のフレームバッファを再バインドしてはいけません。代わりに、defaultFramebufferObject() を呼び出して、バインドすべき ID を取得してください。

QOpenGLWidget では、プラットフォームがサポートしている場合、異なる OpenGL バージョンやプロファイルを使用することができます。setFormat() を通じて、希望するフォーマットを設定するだけです。ただし、同じウィンドウ内に複数の QOpenGLWidget インスタンスが存在する場合、それらはすべて同じフォーマットを使用するか、少なくともコンテキストの共有を妨げないフォーマットを使用する必要がある点に注意してください。この問題を回避するには、setFormat() の代わりにQSurfaceFormat::setDefaultFormat() を使用することを推奨します。

描画手法

前述のように、純粋な 3D コンテンツをレンダリングするには、次のように QOpenGLWidget をサブクラス化します。

• initializeGL() およびresizeGL() 関数を再実装し、OpenGLの状態を設定して、遠近法変換を適用します。
• paintGL() を再実装し、OpenGL 関数のみを呼び出して 3D シーンを描画します。

また、QPainter を使用して、QOpenGLWidget のサブクラス上に 2D グラフィックスを描画することも可能です:

• paintGL() では、OpenGL コマンドを発行する代わりに、ウィジェット上で使用するQPainter オブジェクトを生成します。
• QPainter のメンバ関数を使用してプリミティブを描画します。
• 直接的な OpenGL コマンドの発行も引き続き可能です。ただし、これらのコマンドは、ペインターの beginNativePainting() および endNativePainting() の呼び出しで囲まれていることを確認する必要があります。

QPainter のみを使用して描画を行う場合、通常のウィジェットと同様に、paintEvent() を再実装することで描画を行うことも可能です。

• paintEvent() 関数を再実装します。
• そのウィジェットを対象とするQPainter オブジェクトを構築します。ウィジェットをコンストラクタまたはQPainter::begin() 関数に渡します。
• QPainter のメンバ関数を使用してプリミティブを描画します。
• 描画が完了すると、QPainter インスタンスは破棄されます。あるいは、QPainter::end()を明示的に呼び出すこともできます。

OpenGL 関数呼び出し、ヘッダー、および QOpenGLFunctions

OpenGL 関数を呼び出す際は、関数を直接呼び出すことを避けることを強く推奨します。代わりに、（移植性の高いアプリケーションを作成する場合は）QOpenGLFunctions を使用するか、あるいは（最新のデスクトップ専用 OpenGL をターゲットとする場合は、QOpenGLFunctions_3_2_Core や類似のバージョン指定されたバリアント）を使用することを推奨します。 こうすることで、動的な OpenGL 実装の読み込みを行う構成を含め、すべての Qt ビルド構成においてアプリケーションが正しく動作します。これは、アプリケーションが GL 実装に直接リンクしていないため、直接的な関数呼び出しが実行できないことを意味します。

paintGL() では、QOpenGLContext::currentContext() を呼び出すことで、常に現在のコンテキストにアクセスできます。このコンテキストから、QOpenGLContext::functions() を呼び出すことで、すでに初期化され、使用可能な状態にあるQOpenGLFunctions インスタンスを取得できます。すべての GL 呼び出しに接頭辞を付ける代わりに、QOpenGLFunctions を継承し、initializeGL() 内でQOpenGLFunctions::initializeOpenGLFunctions() を呼び出す方法もあります。

OpenGL のヘッダーについては、ほとんどの場合、GL.h のようなヘッダーを直接インクルードする必要はないことに注意してください。OpenGL 関連の Qt OpenGL ヘッダーは qopengl.h をインクルードしており、qopengl.h はシステムに適したヘッダーをインクルードします。 これは、OpenGL ES 3.x や 2.0 のヘッダー、利用可能な最高バージョンのヘッダー、あるいはシステムが提供する gl.h などである可能性があります。 さらに、OpenGL および OpenGL ES 両方の拡張ヘッダー（一部のシステムでは glext.h と呼ばれる）のコピーが Qt の一部として提供されています。これらは、可能なプラットフォームでは自動的にインクルードされます。つまり、ARB、EXT、OES 拡張からの定数や関数ポインタの typedef が自動的に利用可能になります。

コード例

まず始めに、最も単純な QOpenGLWidget のサブクラスは次のようなものになります：

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);
        ...
    }

};

あるいは、QOpenGLFunctions を継承することで、すべてのOpenGL呼び出しにプレフィックスを付ける手間を省くこともできます：

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

特定のOpenGLバージョンやプロファイルと互換性のあるコンテキストを取得したり、深度バッファやステンシルバッファを要求したりするには、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

OpenGL 3.0 以降のコンテキストにおいて、移植性が重要でない場合は、バージョン指定された `QOpenGLFunctions ` バリアントを使用することで、特定のバージョンで利用可能なすべての最新の OpenGL 関数に簡単にアクセスできます:

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

前述のように、アプリケーションの実行期間中、すべてのウィンドウおよびコンテキストに適用されるよう、要求するフォーマットをグローバルに設定する方が、より簡潔で堅牢です。以下にその例を示します：

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

マルチサンプリング

マルチサンプリングを有効にするには、setFormat() に渡されるQSurfaceFormat で、要求するサンプル数を設定します。マルチサンプリングをサポートしていないシステムでは、この要求は無視される場合があります。

マルチサンプリングをサポートするには、マルチサンプリングされたレンダリングバッファおよびフレームバッファのブリットがサポートされている必要があります。 OpenGL ES 2.0の実装では、これらがサポートされていない可能性が高いです。つまり、マルチサンプリングは利用できません。最新のOpenGLバージョンやOpenGL ES 3.0以降では、通常、これはもはや問題にはなりません。

スレッド処理

たとえば、paintGL() 内で GUI/メインスレッドで使用されるテクスチャを生成するなど、ワーカースレッド上でオフスクリーンレンダリングを実行する場合、ウィジェットの `QOpenGLContext ` を公開することで、各スレッド上でこれと共有する追加のコンテキストを作成できるようになり、これがサポートされます。

GUI/メインスレッド外で QOpenGLWidget のフレームバッファに直接描画するには、paintEvent() を何も行わないように再実装します。コンテキストのスレッドアフィニティは、QObject::moveToThread() を使用して変更する必要があります。その後、ワーカースレッド上でmakeCurrent() およびdoneCurrent() を使用できるようになります。 その後、コンテキストをGUIスレッドまたはメインスレッドに戻すよう注意してください。

QOpenGLWidget のみを対象としたバッファスワップをトリガーすることはできません。これは、QOpenGLWidget には実際の画面上のネイティブサーフェスが存在しないためです。GUI スレッド上での合成およびバッファスワップの管理は、ウィジェットスタックに委ねられています。スレッドがフレームバッファの更新を完了したら、GUI/メインスレッドで update() を呼び出し、合成をスケジュールしてください。

GUI/メインスレッドがコンポジティングを実行している間は、フレームバッファの使用を避けるよう特に注意する必要があります。コンポジティングの開始時および終了時には、aboutToCompose() およびframeSwapped() シグナルが発信されます。これらはGUI/メインスレッド上で発信されます。 つまり、直接接続を使用する場合、aboutToCompose() は、ワーカースレッドがレンダリングを完了するまで GUI/メインスレッドをブロックする可能性があります。その後、ワーカースレッドは、frameSwapped() シグナルが発信されるまで、それ以上のレンダリングを行ってはなりません。 これが許容できない場合は、ワーカースレッドでダブルバッファリングの仕組みを実装する必要があります。これには、スレッドによって完全に制御される代替のレンダリングターゲット（例えば、追加のフレームバッファオブジェクト）を使用して描画を行い、適切なタイミングで QOpenGLWidget のフレームバッファにブリット処理を行うことが含まれます。

コンテキストの共有

複数の QOpenGLWidget が同じ最上位ウィジェットの子として追加されると、それらのコンテキストは互いに共有されます。これは、異なるウィンドウに属する QOpenGLWidget インスタンスには適用されません。

つまり、同じウィンドウ内のすべての QOpenGLWidget は、テクスチャなどの共有可能なリソースに相互にアクセスでき、追加の「グローバル共有」コンテキストは必要ありません。

異なるウィンドウに属する QOpenGLWidget インスタンス間で共有を設定するには、QApplication をインスタンス化する前に、Qt::AA_ShareOpenGLContexts アプリケーション属性を設定してください。これにより、それ以上の手順を必要とせずに、すべての QOpenGLWidget インスタンス間で共有が有効になります。

QOpenGLWidgetのコンテキストとテクスチャなどのリソースを共有する、追加のQOpenGLContext インスタンスを作成することも可能です。QOpenGLContext::create()を呼び出す前に、context()から返されたポインタをQOpenGLContext::setShareContext()に渡すだけです。結果として得られるコンテキストは別のスレッドでも使用できるため、スレッド化されたテクスチャ生成や非同期のテクスチャアップロードが可能になります。

なお、QOpenGLWidget は、基盤となるグラフィックスドライバに関して、標準に準拠したリソース共有の実装を前提としています。例えば、一部のドライバ（特にモバイルや組み込みハードウェア向けのもの）では、既存のコンテキストと後で作成されるコンテキスト間の共有設定に問題が生じることがあります。また、異なるスレッド間で共有リソースを利用しようとすると、予期しない動作をするドライバもあります。

リソースの初期化とクリーンアップ

initializeGL() およびpaintGL() が呼び出される際は、QOpenGLWidget に関連付けられた OpenGL コンテキストが常に最新の状態であることが保証されています。initializeGL() が呼び出される前に OpenGL リソースを作成しようとしないでください。たとえば、サブクラスのコンストラクタ内でシェーダーのコンパイル、頂点バッファオブジェクトの初期化、またはテクスチャデータのアップロードを試みると、失敗します。 これらの操作は、initializeGL() まで延期する必要があります。QOpenGLBuffer やQOpenGLVertexArrayObject などの Qt OpenGL ヘルパークラスの一部は、これに対応する延期動作を持っています。つまり、コンテキストなしでインスタンス化できますが、すべての初期化はcreate() などの呼び出しが行われるまで延期されます。 つまり、これらは QOpenGLWidget のサブクラス内で通常の（ポインタではない）メンバ変数として使用できますが、create() や類似の関数は、initializeGL() からのみ呼び出すことができます。 ただし、すべてのクラスがこのように設計されているわけではない点に注意してください。判断に迷う場合は、メンバ変数をポインタ型にし、initializeGL() 内でインスタンスを動的に生成し、デストラクタ内で破棄するようにしてください。

リソースを解放する際も、コンテキストがアクティブな状態である必要があります。したがって、このようなクリーンアップを行うデストラクタでは、OpenGLリソースやラッパーを破棄する前に、makeCurrent() を呼び出すことが求められます。deleteLater() による遅延削除や、QObject の親子関係メカニズムによる削除は避けてください。当該インスタンスが実際に破棄される時点で、正しいコンテキストがアクティブな状態であるという保証はありません。

したがって、リソースの初期化と破棄に関して、典型的なサブクラスは多くの場合、次のような形になります：

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(...);

    ...
}

これはほとんどの場合に機能しますが、汎用的な解決策としては完全には理想的ではありません。ウィジェットが再親付けされ、まったく異なるトップレベルウィンドウに配置される場合、さらなる対策が必要になります。QOpenGLContext のaboutToBeDestroyed()シグナルに接続することで、OpenGLコンテキストが解放されようとするたびにクリーンアップを実行できるようになります。

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

コンテキストの共有があるため、適切なクリーンアップが特に重要です。各 QOpenGLWidget に関連付けられたコンテキストは QOpenGLWidget とともに破棄されますが、そのコンテキスト内のテクスチャなどの共有可能なリソースは、QOpenGLWidget が存在していた最上位ウィンドウが破棄されるまで有効なままとなります。 さらに、Qt::AA_ShareOpenGLContexts などの設定や一部のQtモジュールにより、コンテキストの共有範囲がさらに広くなる可能性があり、その結果、当該リソースがアプリケーションの存続期間全体にわたって保持され続ける恐れがあります。したがって、最も安全かつ堅牢な方法は、QOpenGLWidgetで使用されたすべてのリソースおよびリソースラッパーに対して、常に明示的なクリーンアップを行うことです。

制限事項およびその他の考慮事項

他のウィジェットを QOpenGLWidget の下に配置し、QOpenGLWidget を透明にしても、期待通りの結果は得られません。つまり、下にあるウィジェットは表示されません。これは、実際には QOpenGLWidget が他のすべての通常の（OpenGL 以外の）ウィジェットよりも先に描画されるためであり、したがって、透過させるような解決策は実現不可能です。 QOpenGLWidgetの上にウィジェットを配置するなどの、他の種類のレイアウトは期待通りに機能します。

どうしても必要な場合は、QOpenGLWidget のQt::WA_AlwaysStackOnTop 属性を設定することで、この制限を回避することができます。 ただし、これにより重ね合わせ順序が破られることに注意してください。例えば、QOpenGLWidgetの上に他のウィジェットを配置することはできなくなるため、この設定は、半透明のQOpenGLWidgetの下に他のウィジェットを表示する必要がある場合にのみ使用すべきです。

なお、下に他のウィジェットがなく、半透明のウィンドウにすることを意図している場合は、この制限は適用されません。その場合は、最上位のウィンドウにQt::WA_TranslucentBackground を設定するという従来の手法で十分です。 なお、QOpenGLWidget内でのみ透過領域が必要な場合は、Qt::WA_TranslucentBackground を有効にした後、Qt::WA_NoSystemBackground をfalse に戻す必要があります。また、システムによっては、setFormat() を通じてQOpenGLWidgetのコンテキストに対してアルファチャネルを要求する必要がある場合もあります。

QOpenGLWidgetは、QOpenGLWindow と同様に、複数の更新挙動をサポートしています。preservedモードでは、前回のpaintGL()呼び出しでレンダリングされた内容が次の呼び出しでも利用可能となり、増分レンダリングが可能になります。non-preservedモードでは、その内容は失われ、paintGL()の実装ではビュー内のすべてを再描画することが求められます。

Qt 5.5 以前、QOpenGLWidget のデフォルトの動作は、paintGL() の呼び出し間でレンダリングされた内容を保持することでした。Qt 5.5 以降、パフォーマンスが向上し、また大多数のアプリケーションでは以前のコンテンツを必要としないため、デフォルトの動作は非保持モードに変更されました。 これは、OpenGLベースのQWindow のセマンティクスにも似ており、各フレームごとに色バッファや補助バッファが無効化されるという点で、QOpenGLWindow のデフォルトの挙動とも一致しています。保存された挙動を復元するには、PartialUpdate を指定してsetUpdateBehavior()を呼び出してください。

QOpenGLWidgetがウィジェット階層に追加されると、トップレベルウィンドウの内容はOpenGLベースのレンダリングによってフラッシュされます。QOpenGLWidget以外のウィジェットは、ソフトウェアベースのペインターを使用して引き続きコンテンツを描画しますが、最終的な合成は3D APIを通じて行われます。

代替手段

ウィンドウに QOpenGLWidget を追加すると、ウィンドウ全体で OpenGL ベースの合成が有効になります。特殊なケースでは、これが理想的ではない場合もあり、独立したネイティブの子ウィンドウを使用する従来の QGLWidget スタイルの挙動が望まれることもあります。 このアプローチの制限事項（例えば、オーバーラップ、透明度、スクロールビュー、MDI領域など）を理解しているデスクトップアプリケーションでは、`QOpenGLWindow ` と `QWidget::createWindowContainer()` を使用できます。これは QGLWidget の現代的な代替手段であり、追加の合成ステップが不要なため、QOpenGLWidget よりも高速です。 このアプローチの使用は、他に選択肢がない場合に限定することを強く推奨します。なお、このオプションはほとんどの組み込みおよびモバイルプラットフォームには適しておらず、特定のデスクトッププラットフォーム（例：macOS）でも問題が発生することが知られています。安定したクロスプラットフォームのソリューションは、常に QOpenGLWidget です。

立体視レンダリング

バージョン 6.5 以降、QOpenGLWidget は立体レンダリングをサポートしています。これを有効にするには、ウィンドウの作成前に QSurfaceFormat::SetDefaultFormat() を使用して、QSurfaceFormat::StereoBuffers フラグをグローバルに設定してください。

これにより、各フレームごとにpaintGL() が 2 回呼び出され、QOpenGLWidget::TargetBuffer ごとに 1 回ずつ実行されます。paintGL() 内で、currentTargetBuffer() を呼び出して、現在描画が行われているバッファを照会してください。

OpenGL は、米国およびその他の国における Silicon Graphics, Inc. の商標です。