QOpenGLWidget Class

詳しい説明

QOpenGLWidgetは、Qtアプリケーションに統合されたOpenGLグラフィックスを表示する機能を提供します。使い方はとても簡単です：あなたのクラスをこのクラスから継承させ、他のQWidget のようにサブクラスを使用します。ただし、QPainter と標準のOpenGLレンダリングコマンドのどちらかを使用することができます。

QOpenGLWidgetは、典型的なOpenGLタスクを実行するために、サブクラスで再実装できる3つの便利な仮想関数を提供します：

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

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

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

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

QOpenGLWidgetは、プラットフォームがサポートしている場合、異なるOpenGLバージョンとプロファイルを使用することができます。setFormat()で要求されたフォーマットを設定するだけです。しかし、同じウィンドウに複数のQOpenGLWidgetインスタンスがある場合、それらのインスタンスがすべて同じフォーマットを使うか、少なくともコンテキストを非シャーラブルにしないフォーマットを使う必要があることに注意してください。この問題を解決するには、setFormat() の代わりにQSurfaceFormat::setDefaultFormat() を使用することをお勧めします。

ペイントテクニック

上述したように、QOpenGLWidgetをサブクラス化して、純粋な3Dコンテンツを以下の方法でレンダリングします：

• 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 と同様のもの）を使用することを好みます。このようにすることで、アプリケーションはすべてのQtビルド構成で正しく動作します。

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

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

コード例

手始めに、最も単純な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のためにバッファ・スワップをトリガーすることはできません。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は、基礎となるグラフィックドライバに関して、リソース共有の標準準拠の実装を期待していることに注意してください。例えば、いくつかのドライバ、特にモバイルや組み込みハードウェア用のドライバは、既存のコンテキストと後から作成された他のコンテキストとの間の共有の設定に問題があります。また、異なるスレッド間で共有リソースを利用しようとすると、予期しない動作をするドライバもあります。

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

QOpenGLWidgetの関連するOpenGLコンテキストは、initializeGL （）とpaintGL （）が呼び出されるたびに、現在であることが保証されます。initializeGL() が呼び出される前に OpenGL リソースを作成しようとしないでください。たとえば、シェーダーをコンパイルしたり、頂点バッファ・オブジェクトを初期化したり、テクスチャー・データをアップロードしようとすると、サブクラスのコンストラクタで実行されたときに失敗します。これらの操作は、initializeGL() に先送りする必要があります。QtのOpenGLヘルパークラスの中には、QOpenGLBuffer やQOpenGLVertexArrayObject のように、同じように遅延させる動作をするものがあります。これらはコンテキストなしでインスタンス化できますが、すべての初期化は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 と同様に、複数の更新動作をサポートしています。保存モードでは、前のpaintGL() 呼び出しからレンダリングされたコンテンツは、次の呼び出しで利用可能であり、インクリメンタルなレンダリングが可能です。非保存モードでは、コンテンツは失われ、paintGL() の実装は、ビュー内のすべてを再描画することが期待されます。

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

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

代替方法

QOpenGLWidgetをウィンドウに追加すると、ウィンドウ全体のOpenGLベースの合成が有効になります。いくつかの特殊なケースでは、これは理想的ではなく、独立したネイティブの子ウィンドウを持つ古いQGLWidgetスタイルの動作が望まれます。このアプローチの限界（オーバーラップ、透明度、スクロールビュー、MDIエリアなど）を理解しているデスクトップアプリケーションは、QWidget::createWindowContainer （）を使ってQOpenGLWindow 。これはQGLWidgetの現代的な代替であり、追加の合成ステップがないため、QOpenGLWidgetよりも高速です。この方法の使用は、他に選択肢がない場合に限定することを強く推奨します。このオプションは、ほとんどの組み込みプラットフォームやモバイルプラットフォームには適しておらず、特定のデスクトッププラットフォーム（例えばmacOS）でも問題があることが知られていることに注意してください。安定したクロスプラットフォームのソリューションは、常にQOpenGLWidgetです。

ステレオスコピックレンダリング

6.5以降、QOpenGLWidgetはステレオスコピックレンダリングをサポートしています。これを有効にするには、QSurfaceFormat::SetDefaultFormat() を使用して、ウィンドウが作成される前にQSurfaceFormat::StereoBuffers フラグをグローバルに設定します。

QOpenGLWidget::TargetBufferこの場合、paintGL() が各フレームごとに 2 回呼び出されます。paintGL() では、currentTargetBuffer() を呼び出して、現在描画されているのがどれであるかを問い合わせます。

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