QOffscreenSurface Class
QOffscreenSurface クラスは、基盤となるプラットフォーム上のオフスクリーン・サーフェスを表します。詳細...
| ヘッダー： | #include <QOffscreenSurface> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| 継承元: | QObject およびQSurface |
パブリック関数
| QOffscreenSurface(QScreen *targetScreen = nullptr, QObject *parent = nullptr) | |
| virtual | ~QOffscreenSurface() |
| void | create() |
| void | destroy() |
| bool | isValid() const |
| QNativeInterface * | nativeInterface() const |
| QSurfaceFormat | requestedFormat() const |
| QScreen * | screen() const |
| void | setFormat(const QSurfaceFormat &format) |
| void | setScreen(QScreen *newScreen) |
再実装されたパブリック関数
| virtual QSurfaceFormat | format() const override |
| virtual QSize | size() const override |
| virtual QSurface::SurfaceType | surfaceType() const override |
シグナル
| void | screenChanged(QScreen *screen) |
詳細な説明
QOffscreenSurface は、QOpenGLContext と併用して、QWindow を作成することなく、任意のスレッドで OpenGL によるレンダリングを行うことを目的としています。
通常、このサーフェスはレンダリング可能ですが、そのピクセルにはアクセスできません。QOffscreenSurface は、テクスチャやフレームバッファオブジェクトなどの OpenGL リソースを作成するためにのみ使用してください。
アプリケーションでは通常、メインのレンダリングスレッドの停止を回避するために、QOffscreenSurface を使用して、別のスレッドで時間のかかるタスクを実行します。QOffscreenSurface のコンテキストで作成されたリソースは、メインの OpenGL コンテキストと共有できます。一般的な使用例としては、非同期のテクスチャアップロードや、QOpenGLFramebufferObject へのレンダリングなどが挙げられます。
オフスクリーンサーフェスの実装方法は基盤となるプラットフォームに依存しますが、通常はピクセルバッファ（pbuffer）が使用されます。プラットフォームがオフスクリーンサーフェスを実装またはサポートしていない場合、QOffscreenSurfaceは内部で非表示のQWindow を使用します。
注： 一部のプラットフォームでは、QOffscreenSurfaceがQWindow によって裏付けられているため、 クロスプラットフォームアプリケーションでは、create()がメイン（GUI）スレッド上でのみ呼び出されるようにする必要があります。 そうすれば、QOffscreenSurface は他のスレッドでmakeCurrent() とともに安全に使用できますが、初期化と破棄は常にメイン（GUI）スレッドで行わなければなりません。
注： 特定のコンテキストやウィンドウとの互換性が保証されたオフスクリーンサーフェスを作成するには、 フォーマットをコンテキストまたはウィンドウの実際のフォーマット、つまり、コンテキストまたはウィンドウの作成後に`QOpenGLContext::format()` または `QWindow::format()` から返される `QSurfaceFormat ` に設定してください。QWindow::requestedFormat() から返されたフォーマットをsetFormat() に渡すと、基盤となるウィンドウシステムインターフェースがウィンドウ用と pbuffer サーフェス用に異なる設定セットを提供している可能性があるため、互換性のないオフスクリーンサーフェスが生成される可能性があります。
注：一部のプラットフォームでは 、利用可能な場合、サーフェスレスコンテキスト拡張（例：EGL_KHR_surfaceless_context）が使用されることがあります。この場合、基盤となるネイティブサーフェスは存在しません。QOffscreenSurface の使用ケース（FBO へのレンダリング、テクスチャのアップロード）においては、これは問題になりません。
メンバ関数のドキュメント
[explicit] QOffscreenSurface::QOffscreenSurface(QScreen *targetScreen = nullptr, QObject *parent = nullptr)
指定されたparent を使用して、targetScreen 用のオフスクリーンサーフェスを作成します。
create() が呼び出されるまで、基盤となるプラットフォームサーフェスは作成されません。
setScreen() およびcreate()も参照してください 。
[virtual noexcept] QOffscreenSurface::~QOffscreenSurface()
画面外にあるサーフェスを破棄します。
void QOffscreenSurface::create()
オフスクリーン・サーフェスに関連付けられたプラットフォーム・リソースを割り当てます。
この時点で、setFormat() を使用して設定されたサーフェス形式が、実際のネイティブサーフェスとして解決されます。
必要に応じて、destroy() を呼び出してプラットフォームリソースを解放してください。
注：プラットフォームによっては 、この関数をメイン（GUI）スレッドで呼び出す必要があります。
destroy()も参照してください 。
void QOffscreenSurface::destroy()
このオフスクリーン・サーフェスに関連付けられているネイティブ・プラットフォームのリソースを解放します。
create()も参照してください 。
[override virtual] QSurfaceFormat QOffscreenSurface::format() const
QSurface::format() const を再実装します。
このオフスクリーンサーフェスの実際のフォーマットを返します。
オフスクリーンサーフェスが作成された後、この関数はそのサーフェスの実際のフォーマットを返します。プラットフォームが要求されたフォーマットを満たせなかった場合、実際のフォーマットは要求されたフォーマットと異なる可能性があります。
setFormat()、create()、およびrequestedFormat()も参照してください 。
bool QOffscreenSurface::isValid() const
このオフスクリーンサーフェスが有効な場合は `true ` を返し、そうでない場合は `false` を返します。
プラットフォームリソースの割り当てが正常に行われた場合、このオフスクリーンサーフェスは有効となります。
create()も参照してください 。
template <typename QNativeInterface> QNativeInterface *QOffscreenSurface::nativeInterface() const
指定された型の、そのサーフェスに対するネイティブインターフェースを返します。
この関数は、QNativeInterface 名前空間で定義されているQOffScreenSurfaceのプラットフォーム固有の機能へのアクセスを提供します:
Android上のオフスクリーンサーフェスへのネイティブインターフェース |
要求されたインターフェースが利用できない場合は、nullptr が返されます。
QSurfaceFormat QOffscreenSurface::requestedFormat() const
このオフスクリーン・サーフェスの、指定されたサーフェスフォーマットを返します。
要求されたフォーマットがプラットフォームの実装でサポートされていない場合、requestedFormat は実際のオフスクリーン・サーフェスのフォーマットとは異なります。
これは、setFormat() で設定された値です。
setFormat() およびformat()も参照してください 。
QScreen *QOffscreenSurface::screen() const
オフスクリーンサーフェスが接続されている画面を返します。
setScreen()も参照してください 。
[signal] void QOffscreenSurface::screenChanged(QScreen *screen)
このシグナルは、オフスクリーン面のscreen が変更されたときに発生します。これは、setScreen() によって明示的に設定された場合、あるいはウィンドウの画面が削除された際に自動的に設定された場合です。
void QOffscreenSurface::setFormat(const QSurfaceFormat &format)
オフスクリーン・サーフェス「format 」を設定します。
サーフェス形式は、create() 関数内で解決されます。create() の後にこの関数を呼び出しても、ネイティブサーフェスの形式は再解決されません。
format()、create()、およびdestroy()も参照してください 。
void QOffscreenSurface::setScreen(QScreen *newScreen)
オフスクリーンサーフェスが接続される画面を設定します。
オフスクリーンサーフェスがすでに作成されている場合、newScreen 上で再作成されます。
screen()も参照してください 。
[override virtual] QSize QOffscreenSurface::size() const
QSurface::size() const を再実装します。
オフスクリーン・サーフェスのサイズを返します。
[override virtual] QSurface::SurfaceType QOffscreenSurface::surfaceType() const
QSurface::surfaceType() const を再実装します。
オフスクリーン・サーフェスのサーフェス型を返します。
オフスクリーン・サーフェスのサーフェス・タイプは、常に `QSurface::OpenGLSurface` です。
© 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.
