QQuickWindow Class

メンバ関数のドキュメント

[explicit] QQuickWindow::QQuickWindow(QQuickRenderControl *control)

QMLシーンを表示するためのウィンドウを構築します。このウィンドウのレンダリングは、control オブジェクトによって制御されます。詳細については、QQuickRenderControl のドキュメントを参照してください。

[explicit] QQuickWindow::QQuickWindow(QWindow *parent = nullptr)

親ウィンドウparent を持つQMLシーンを表示するためのウィンドウを作成します。

[override virtual noexcept] QQuickWindow::~QQuickWindow()

ウィンドウを閉じます。

[override virtual] QAccessibleInterface *QQuickWindow::accessibleRoot() const

このウィンドウのアクセシビリティインターフェースを返します。そのようなインターフェースを作成できない場合は、0を返します。

[signal] void QQuickWindow::afterAnimating()

このシグナルは、レンダリングスレッドに対してシーングラフの同期処理を実行するよう要求する前に、GUIスレッド上で発火されます。

他の類似のシグナルとは異なり、このシグナルはレンダリングスレッドではなくGUIスレッド上で発火します。これは、外部のアニメーションシステムとQMLコンテンツを同期させるために使用できます。同時に、このシグナルはグラフィックス操作をトリガーするには適していないことを意味します。

[signal, since 6.0] void QQuickWindow::afterFrameEnd()

このシグナルは、シーングラフがフレームを送信したときに発火します。これは、afterRendering() など、他の関連するすべてのシグナルが発火した後に発火します。これは、フレームのレンダリング時にシーングラフのレンダリングスレッドによって発火される最後のシグナルです。

この関数は Qt 6.0 で導入されました。

beforeFrameBegin() およびrendererInterface()も参照してください 。

[signal] void QQuickWindow::afterRenderPassRecording()

このシグナルは、シーングラフがメインのレンダリングパスに関するコマンドを記録した後、そのパスがコマンドバッファ上でまだ確定していない段階で発せられます。

このシグナルは、afterRendering() よりも前に発行され、フレームだけでなく、シーングラフのメインレンダリングパスの記録もまだアクティブであることを保証します。これにより、別のレンダリングパスを完全に生成することなく（通常、これによりアタッチされた画像がクリアされてしまいます）、コマンドを挿入することが可能になります。ネイティブグラフィックスオブジェクトは、QSGRendererInterface を通じて照会できます。

rendererInterface() およびQML の「シーングラフ - RHI」も参照してください 。

[signal] void QQuickWindow::afterRendering()

このシグナルは、シーングラフがそのコマンドをコマンドバッファに追加した後、そのコマンドがまだグラフィックスキューに送信されていない時点で発せられます。 必要に応じて、このシグナルに接続されたスロット関数では、QSGRendererInterface を通じて、コマンドバッファなどのネイティブリソースを事前に照会できます。ただし、この時点ですでにレンダリングパス（または複数のパス）が記録済みであり、シーングラフのパス内にコマンドを追加することはできない点に注意してください。 その場合は、代わりに `afterRenderPassRecording()` を使用してください。したがって、Qt 5 とは異なり、Qt 6 ではこのシグナルの用途は限られています。むしろ、カスタムレンダリングのアンダーレイやオーバーレイを実現するには、通常、`beforeRendering()` と `beforeRenderPassRecording()`、あるいは `beforeRendering()` と `afterRenderPassRecording()` の組み合わせが使用されます。

関連項目： rendererInterface()、QML におけるシーングラフ - RHI、QML におけるシーングラフ - OpenGL、QML におけるシーングラフ - Metal、QML におけるシーングラフ - Vulkan、およびQML におけるシーングラフ - Direct3D 11。

[signal] void QQuickWindow::afterSynchronizing()

このシグナルは、シーングラフが QML 状態と同期された後に発火します。

このシグナルを使用すると、GUIスレッドがまだロックされている間に、QQuickItem::updatePaintNode() の呼び出し後に必要な準備を行うことができます。

OpenGL を使用する場合、この時点で、シーングラフによるレンダリングに使用される `QOpenGLContext ` がバインドされます。

[signal, since 6.0] void QQuickWindow::beforeFrameBegin()

このシグナルは、シーングラフがフレームの準備を開始する前に発火します。これは、beforeSynchronizing() やbeforeRendering() といったシグナルよりも先に発火します。これは、シーングラフのレンダリングスレッドが新しいフレームの準備を開始する際に発火する、最も早いシグナルです。

このシグナルは、Qt Quick が基盤となるレンダリングハードウェアインターフェース API を通じて新しいフレームの記録を開始していない段階で、リソースのクリーンアップなどの特定の操作を実行する必要がある、低レベルのグラフィックスフレームワークに関連しています。

この関数は Qt 6.0 で導入されました。

afterFrameEnd() およびrendererInterface()も参照してください 。

[signal] void QQuickWindow::beforeRenderPassRecording()

このシグナルは、シーングラフがメインのレンダリングパスのコマンドの記録を開始する前に発せられます（レイヤーにはそれぞれ独自のパスがあり、このシグナルが発せられる時点ですでに完全に記録されています）。シグナルが発せられた時点で、コマンドバッファ上ではすでにレンダリングパスがアクティブになっています。

このシグナルは `beforeRendering()` よりも後に発火し、フレームだけでなく、シーングラフのメインレンダリングパスの記録もアクティブであることを保証します。これにより、別途のレンダリングパス全体を生成することなく（通常、これを行うとアタッチされた画像がクリアされてしまいます）、コマンドを挿入することが可能になります。ネイティブグラフィックスオブジェクトは `QSGRendererInterface` を通じて照会できます。

rendererInterface() および「QML のシーングラフ - RHI」も参照してください 。

[signal] void QQuickWindow::beforeRendering()

この信号は、フレームの準備が完了した後に発信されます。つまり、該当する場合、コマンドバッファが記録モードになっていることを意味します。 必要に応じて、この信号に接続されたスロット関数は、QSGRendererInterface を通じて、前述のコマンドのようなネイティブリソースを照会できます。ただし、この時点ではメインのレンダリングパスの記録はまだ開始されておらず、そのパス内にコマンドを追加することはできない点に注意してください。 パスの開始とは、カラーバッファ、深度バッファ、ステンシルバッファをクリアすることを意味するため、このシグナルに接続するだけではアンダーレイ型のレンダリングを実現することはできません。その場合は、beforeRenderPassRecording() に接続してください。ただし、コピー型のコマンドの記録を希望する場合は、このシグナルへの接続が依然として重要です。なぜなら、それらのコマンドはレンダリングパス内でキューに追加できないからです。

関連項目： rendererInterface()、QML におけるシーングラフ - RHI、QML におけるシーングラフ - OpenGL、QML におけるシーングラフ - Metal、QML におけるシーングラフ - Vulkan、およびQML におけるシーングラフ - Direct3D 11。

[signal] void QQuickWindow::beforeSynchronizing()

このシグナルは、シーングラフがQMLの状態と同期される前に発火します。

このシグナルはシーングラフのレンダリングスレッドから発火されますが、QQuickItem::updatePaintNode() の場合と同様に、GUI スレッドがブロックされることが保証されています。したがって、Qt::DirectConnection に接続されたスロットやラムダ内で、GUI スレッドのデータにアクセスしても安全です。

このシグナルを使用することで、QQuickItem::updatePaintNode() を呼び出す前に必要な準備を行うことができます。

OpenGL を使用する場合、この時点でシーングラフによるレンダリングに使用される `QOpenGLContext ` がバインドされます。

void QQuickWindow::beginExternalCommands()

生のグラフィックス（OpenGL、Vulkan、Metal など）コマンドをシーングラフによるレンダリングと組み合わせる場合、シーングラフがメインのレンダリングパスをレンダリングするために使用するコマンドバッファにコマンドを書き込む前に、この関数を呼び出す必要があります。これは、状態が上書きされるのを防ぐためです。

実際には、この関数はbeforeRenderPassRecording()やafterRenderPassRecording()シグナルに接続されたスロットから呼び出されることがよくあります。

アプリケーション独自のコマンドバッファ（シーングラフから取得したものではなく、アプリケーションによって作成・管理される VkCommandBuffer や MTLCommandBuffer + MTLRenderCommandEncoder など）にコマンドを書き込む場合は、この関数を呼び出す必要はありません。 ネイティブなコマンドバッファの概念が公開されていないグラフィックス API（OpenGL、Direct 3D 11）では、beginExternalCommands() とendExternalCommands() を組み合わせることで、Qt 5 の resetOpenGLState() 関数の代わりとなります。

QSGRenderNode のrender() 実装内では、この関数およびendExternalCommands() を呼び出す必要はありません。これは、シーングラフがレンダリングノードに対して必要な手順を暗黙的に実行するためです。

ネイティブのグラフィックスオブジェクト（グラフィックスデバイス、コマンドバッファ、エンコーダなど）には、QSGRendererInterface::getResource() を通じてアクセスできます。

関連項目： endExternalCommands() およびQQuickOpenGLUtils::resetOpenGLState()。

[override virtual protected] void QQuickWindow::closeEvent(QCloseEvent *e)

QWindow::closeEvent （QCloseEvent *ev）を再実装します。

QSGImageNode *QQuickWindow::createImageNode() const

単純な画像ノードを作成します。シーングラフが初期化されていない場合、戻り値は null になります。

これは、QSGSimpleTextureNode を直接生成する代わりに使用できる、バックエンドを問わない代替手段です。

QSGImageNodeも参照してください 。

QSGNinePatchNode *QQuickWindow::createNinePatchNode() const

9パッチノードを作成します。シーングラフが初期化されていない場合、戻り値はnullになります。

QSGRectangleNode *QQuickWindow::createRectangleNode() const

単純な矩形ノードを作成します。シーングラフが初期化されていない場合、戻り値はnullとなります。

これは、QSGSimpleRectNode を直接生成する代わりに、バックエンドを問わず利用できる代替手段です。

QSGRectangleNodeも参照してください 。

[since 6.7] QSGTextNode *QQuickWindow::createTextNode() const

テキストノードを作成します。シーングラフが初期化されていない場合、戻り値は null になります。

この関数は Qt 6.7 で導入されました。

QSGTextNodeも参照してください 。

QSGTexture *QQuickWindow::createTextureFromImage(const QImage &image, QQuickWindow::CreateTextureOptions options) const

指定されたimage から新しいQSGTexture を作成します。画像にアルファチャンネルがある場合、対応するテクスチャにもアルファチャンネルが含まれます。

返されたテクスチャの削除は、この関数を呼び出した側が責任を持って行う必要があります。その後、基になるネイティブテクスチャオブジェクトは、QSGTexture とともに破棄されます。

options にTextureCanUseAtlas が含まれている場合、エンジンはその画像をテクスチャアトラスに配置することがあります。アトラス内のテクスチャは、ジオメトリの取得にQSGTexture::normalizedTextureSubRect()に依存する必要があり、QSGTexture::Repeat はサポートされません。CreateTextureOption のその他の値は無視されます。

options にTextureIsOpaque が指定されている場合、エンジンはQSGTexture::hasAlphaChannel()に対してfalseを返すRGBテクスチャを作成します。不透明なテクスチャは、ほとんどの場合、レンダリングが高速になります。このフラグが設定されていない場合、テクスチャは画像のフォーマットに基づいたアルファチャンネルを持ちます。

options にTextureHasMipmaps が指定されている場合、エンジンはミップマップフィルタリングを使用できるテクスチャを作成します。ミップマップ化されたテクスチャはアトラスに含めることはできません。

この関数では、アルファチャンネルとブレンディングがデフォルトで想定されているため、`TextureHasAlphaChannel `を`options `に設定しても意味がありません。これを無効にするには、`TextureIsOpaque`を設定してください。

シーングラフが OpenGL を使用する場合、返されるテクスチャは、テクスチャターゲットとして `GL_TEXTURE_2D `、内部フォーマットとして `GL_RGBA ` を使用します。他のグラフィックス API では、テクスチャフォーマットは通常 `RGBA8` になります。異なるパラメータでテクスチャを作成するには、QSGTexture を再実装してください。

この関数は、メインスレッドとレンダリングスレッドの両方から呼び出すことができます。

sceneGraphInitialized() およびQSGTextureも参照してください 。

QSGTexture *QQuickWindow::createTextureFromImage(const QImage &image) const

[since 6.6] QSGTexture *QQuickWindow::createTextureFromRhiTexture(QRhiTexture *texture, QQuickWindow::CreateTextureOptions options = {}) const

指定されたtexture から、新しいQSGTexture を作成します。

options を使用して、テクスチャ属性をカスタマイズします。この関数では、TextureHasAlphaChannel フラグのみが考慮されます。このフラグが設定されている場合、生成されたQSGTexture は、シーングラフレンダラーによって常にブレンディングが必要なものと扱われます。完全に不透明なテクスチャの場合、このフラグを設定しないことで、レンダリング時のアルファブレンディング処理にかかるコストを節約できます。 このフラグは、QRhiTexture のformat とは直接対応していません。つまり、一般的に使用されるQRhiTexture::RGBA8 などのテクスチャ形式を使用している場合でも、このフラグを設定しないことはまったく問題ありません。

ミップマッピングは、options によって制御されません。これは、texture がすでに作成されており、ミップマップの有無がそこに焼き込まれているためです。

返されるQSGTexture はQRhiTexture を所有しているため、texture は返されたQSGTexture とともに破棄されます。

texture が基になるネイティブグラフィックスリソース（OpenGLテクスチャオブジェクト、Vulkanイメージなど）を所有しているかどうかは、QRhiTexture の作成方法（QRhiTexture::create() またはQRhiTexture::createFrom()）に依存し、この関数によって制御または変更されるものではありません。

この関数は Qt 6.6 で導入されました。

関連項目： createTextureFromImage()、sceneGraphInitialized()、およびQSGTexture 。

[signal, since 6.11] void QQuickWindow::devicePixelRatioChanged()

このシグナルは、実効デバイス画素比が変更されたときに発信されます。

この関数は Qt 6.11 で導入されました。

effectiveDevicePixelRatio()も参照してください 。

qreal QQuickWindow::effectiveDevicePixelRatio() const

このウィンドウのデバイスピクセル比を返します。

これは、QWindow::devicePixelRatio() とは異なり、QQuickRenderControl およびQQuickRenderTarget によるリダイレクトされたレンダリングをサポートしている点が異なります。QQuickRenderControl を使用する場合、QQuickWindow は多くの場合完全に作成されないため、表示されることはなく、ウィンドウシステム内に基礎となるネイティブウィンドウも作成されません。 その結果、デバイスピクセル比などのプロパティを照会しても、正しい結果が得られません。この関数は、QQuickRenderControl::renderWindowFor() とQQuickRenderTarget::devicePixelRatio() の両方を考慮に入れています。リダイレクトが有効でない場合、結果はQWindow::devicePixelRatio() と同じになります。

関連項目： QQuickRenderControl 、QQuickRenderTarget 、setRenderTarget()、およびQWindow::devicePixelRatio()。

void QQuickWindow::endExternalCommands()

生のグラフィックス（OpenGL、Vulkan、Metalなど）のコマンドとシーングラフによるレンダリングを組み合わせる場合、シーングラフがメインのレンダリングパスをレンダリングするために使用するコマンドバッファにコマンドを書き込んだ後、この関数を呼び出す必要があります。これは、状態が上書きされるのを防ぐためです。

実際には、この関数はbeforeRenderPassRecording()やafterRenderPassRecording()シグナルに接続されたスロットから呼び出されることがよくあります。

アプリケーション独自のコマンドバッファ（シーングラフから取得したものではなく、アプリケーションによって作成・管理される VkCommandBuffer や MTLCommandBuffer + MTLRenderCommandEncoder など）にコマンドを書き込む場合は、この関数を呼び出す必要はありません。 ネイティブなコマンドバッファの概念が公開されていないグラフィックスAPI（OpenGL、Direct 3D 11）では、beginExternalCommands() と endExternalCommands() を組み合わせることで、Qt 5 の resetOpenGLState() 関数の代替機能を提供します。

QSGRenderNode のrender() 実装内では、この関数とbeginExternalCommands() を呼び出す必要はありません。これは、シーングラフがレンダリングノードに対して必要な手順を暗黙的に実行するためです。

beginExternalCommands() およびQQuickOpenGLUtils::resetOpenGLState()も参照してください 。

[override virtual protected] bool QQuickWindow::event(QEvent *event)

QWindow::event(QEvent *ev) を再実装しています。

[override virtual protected] void QQuickWindow::exposeEvent(QExposeEvent *)

QWindow::exposeEvent （QExposeEvent *ev）を再実装しています。

[override virtual protected] void QQuickWindow::focusInEvent(QFocusEvent *ev)

QWindow::focusInEvent(QFocusEvent *ev) を再実装します。

[override virtual protected] void QQuickWindow::focusOutEvent(QFocusEvent *ev)

QWindow::focusOutEvent(QFocusEvent *ev) を再実装します。

[signal] void QQuickWindow::frameSwapped()

このシグナルは、フレームがレンダリングのためにキューに入れられたときに発せられます。垂直同期が有効になっている場合、連続してアニメーションが再生されているシーンでは、このシグナルはvsyncインターバルごとに最大1回発せられます。

このシグナルは、シーングラフのレンダリングスレッドから発火されます。

QImage QQuickWindow::grabWindow()

ウィンドウの内容を取得し、画像として返します。

ウィンドウが表示されていない状態でも、grabWindow() 関数を呼び出すことは可能です。ただし、その場合は、ウィンドウが `created ` であり、有効なサイズを持ち、かつ同じプロセス内で他の `QQuickWindow ` インスタンスがレンダリングされていないことが条件となります。

[static, since 6.0] QSGRendererInterface::GraphicsApi QQuickWindow::graphicsApi()

この時点でシーングラフが初期化された場合に使用されるグラフィックスAPIを返します。

シーングラフが使用するAPIを照会する標準的な方法は、シーングラフの初期化が完了した後（例えば、sceneGraphInitialized()シグナルが発信されたとき、またはその直後など）にQSGRendererInterface::graphicsApi()を使用することです。その場合、そのグラフィックスAPIを使用してすべてが正しく初期化されたことが確認できるため、真の結果が得られます。

しかし、これは必ずしも便利とは限りません。アプリケーションが外部フレームワークを設定する必要がある場合や、シーングラフに組み込まれたAPI選択ロジックに依存する形でsetGraphicsDevice()を使用する必要がある場合、QQuickWindow が可視化されるか、QQuickRenderControl::initialize()が呼び出されるまで、そのような操作を先送りすることが常に可能とは限りません。

そのため、setGraphicsApi() の対となるものとして、この静的関数が提供されています。これはいつでも呼び出すことができ、その結果は、呼び出しの時点でシーングラフが初期化されていた場合にシーングラフが選択するであろう API を反映しています。

この関数は Qt 6.0 で導入されました。

setGraphicsApi()も参照してください 。

[since 6.0] QQuickGraphicsConfiguration QQuickWindow::graphicsConfiguration() const

setGraphicsConfiguration() に渡された `QQuickGraphicsConfiguration ` を返します。それ以外の場合は、デフォルト構築されたオブジェクトを返します。

この関数は Qt 6.0 で導入されました。

setGraphicsConfiguration()も参照してください 。

[since 6.0] QQuickGraphicsDevice QQuickWindow::graphicsDevice() const

setGraphicsDevice() に渡された `QQuickGraphicsDevice ` を返します。それ以外の場合は、デフォルト生成されたものを返します

この関数は Qt 6.0 で導入されました。

setGraphicsDevice()も参照してください 。

const QQuickWindow::GraphicsStateInfo &QQuickWindow::graphicsStateInfo()

RHIの内部状態の一部、特にバックエンド（VulkanやMetalの統合など）のダブルバッファリングまたはトリプルバッファリングの状態を表すGraphicsStateInfo 構造体への参照を返します。 これは、基盤となるグラフィックスAPIがVulkanまたはMetalであり、外部のレンダリングコードが、パイプラインのストール（停止）を回避するために、ユニフォームバッファなど、頻繁に変化するリソースに対して独自のダブルバッファリングまたはトリプルバッファリングを実行したい場合に適用されます。

[static] bool QQuickWindow::hasDefaultAlphaBuffer()

新しく作成されるウィンドウでアルファ透過を使用するかどうかを返します。

setDefaultAlphaBuffer()も参照してください 。

[override virtual protected] void QQuickWindow::hideEvent(QHideEvent *)

QWindow::hideEvent(QHideEvent *ev) を再実装します。

QQmlIncubationController *QQuickWindow::incubationController() const

このウィンドウのフレーム間でインキュベーションをスプライスするインキュベーションコントローラを返します。QQuickView では、このコントローラが自動的にインストールされますが、そうでない場合は、QQmlEngine::setIncubationController() を使用して手動でインストールする必要があります。

このコントローラーはウィンドウが所有しており、ウィンドウが削除されると破棄されます。

bool QQuickWindow::isPersistentGraphics() const

QQuickWindow の存続期間中に、必須のグラフィックリソースを解放できるかどうかを返します。

関連項目 :setPersistentGraphics()

bool QQuickWindow::isPersistentSceneGraph() const

このQQuickWindow の存続期間中に、シーングラフのノードおよびリソースを解放できるかどうかを返します。

bool QQuickWindow::isSceneGraphInitialized() const

シーングラフが初期化されている場合は true を返し、そうでない場合は false を返します。

[override virtual protected] void QQuickWindow::keyPressEvent(QKeyEvent *e)

QWindow::keyPressEvent （QKeyEvent *ev）を再実装します。

[override virtual protected] void QQuickWindow::keyReleaseEvent(QKeyEvent *e)

QWindow::keyReleaseEvent(QKeyEvent *ev) を再実装します。

[override virtual protected] void QQuickWindow::mouseDoubleClickEvent(QMouseEvent *event)

QWindow::mouseDoubleClickEvent(QMouseEvent *ev) を再実装します。

[override virtual protected] void QQuickWindow::mouseMoveEvent(QMouseEvent *event)

QWindow::mouseMoveEvent(QMouseEvent *ev) を再実装します。

[override virtual protected] void QQuickWindow::mousePressEvent(QMouseEvent *event)

QWindow::mousePressEvent(QMouseEvent *ev) を再実装します。

[override virtual protected] void QQuickWindow::mouseReleaseEvent(QMouseEvent *event)

QWindow::mouseReleaseEvent(QMouseEvent *ev) を再実装します。

[slot] void QQuickWindow::releaseResources()

この関数は、QMLシーンが現在保持している不要なリソースを解放しようとします。

この関数を呼び出すと、シーングラフに対して、グラフィックスパイプラインオブジェクト、シェーダープログラム、画像データなどのキャッシュされたグラフィックスリソースを解放するよう要求します。

さらに、使用中のレンダリングループによっては、この関数の呼び出しにより、シーングラフおよびウィンドウに関連するすべてのレンダリングリソースが解放される場合もあります。その場合は、sceneGraphInvalidated() シグナルが発行され、ユーザーは自身のグラフィックリソースをクリーンアップすることができます。 アプリケーション側でクリーンアップ処理を行うことが不可能な場合、setPersistentGraphics() およびsetPersistentSceneGraph() 関数を使用してこれを防ぐことができますが、その場合はメモリ使用量が増えるという代償が伴います。

関連項目： sceneGraphInvalidated()、setPersistentGraphics()、およびsetPersistentSceneGraph()。

[since 6.0] QQuickRenderTarget QQuickWindow::renderTarget() const

setRenderTarget() に渡されたQQuickRenderTarget を返します。それ以外の場合は、デフォルト構築された を返します

この関数は Qt 6.0 で導入されました。

setRenderTarget()も参照してください 。

QSGRendererInterface *QQuickWindow::rendererInterface() const

現在のレンダラーインターフェースを返します。この値は常に有効であり、nullになることはありません。

「 QSGRenderNode 」および「QSGRendererInterface 」も参照してください 。

[override virtual protected] void QQuickWindow::resizeEvent(QResizeEvent *ev)

QWindow::resizeEvent(QResizeEvent *ev) を再実装します。

[since 6.6] QRhi *QQuickWindow::rhi() const

このウィンドウがレンダリングに使用するQRhi オブジェクトを返します。

この関数は、ウィンドウがQt 3D APIおよびシェーディング言語の抽象化機能を使用している場合にのみ利用可能です。つまり、software アダプテーションを使用している場合は、結果は常にnullとなります。

結果は、レンダリングが初期化された場合にのみ有効であり、これはsceneGraphInitialized()シグナルの発火によって示されます。その時点以前は、戻り値はnullになります。通常の画面上のQQuickWindow では、シーングラフの初期化は通常、ネイティブウィンドウが最初に公開（表示）されたときに行われます。QQuickRenderControl を使用する場合、初期化はinitialize()を明示的に呼び出すことで行われます。

実際には、この関数はQSGRendererInterface を介してQRhi を照会するための近道となっています。

この関数は Qt 6.6 で導入されました。

[signal] void QQuickWindow::sceneGraphAboutToStop()

このシグナルは、シーングラフがレンダリングを停止しようとしている際に、レンダリングスレッドで発火します。これは通常、ウィンドウが非表示になったことが原因で発生します。

アプリケーションはこのシグナルを利用してリソースを解放できますが、それらを迅速に再インスタンス化できるよう準備しておく必要があります。この時点では、シーングラフとグラフィックスコンテキストは解放されません。

sceneGraphInvalidated()も参照してください 。

[static] QString QQuickWindow::sceneGraphBackend()

指定されたQt Quick のシーングラフバックエンドを返します。

setSceneGraphBackend()も参照してください 。

[signal] void QQuickWindow::sceneGraphError(QQuickWindow::SceneGraphError error, const QString &message)

このシグナルは、シーングラフの初期化中にerror が発生した際に発火します。

グラフィックコンテキストの作成失敗などのエラーを独自の方法で処理したい場合は、アプリケーションはこのシグナルに接続する必要があります。このシグナルにスロットが接続されていない場合、動作は異なります。Quickはmessage を出力するか、メッセージボックスを表示して、アプリケーションを終了します。

このシグナルはGUIスレッドから発せられます。

[signal] void QQuickWindow::sceneGraphInitialized()

このシグナルは、シーングラフの初期化が完了したときに発火します。

このシグナルは、シーングラフのレンダリングスレッドから発せられます。

[signal] void QQuickWindow::sceneGraphInvalidated()

このシグナルは、シーングラフが無効化されたときに発信されます。

このシグナルは、使用されていたグラフィックス・レンダリング・コンテキストが無効化されたことを意味し、そのコンテキストに関連付けられていたすべてのユーザーリソースを解放する必要があります。

OpenGL を使用してレンダリングする場合、この関数が呼び出されると、このウィンドウのQOpenGLContext がバインドされます。唯一の例外は、EGL_CONTEXT_LOST などを通じて、Qt の制御外でネイティブ OpenGL が破棄された場合です。

このシグナルは、シーングラフのレンダリングスレッドから発せられます。

void QQuickWindow::scheduleRenderJob(QRunnable *job, QQuickWindow::RenderStage stage)

このウィンドウのレンダリングが指定されたstage に到達した際に、job を実行するようにスケジュールします。

これは、「ワンショット」タスクに対する `QQuickWindow ` の同等のシグナルに対する便宜的な機能です。

ウィンドウは `job ` の所有権を取得し、ジョブが完了したらそれを削除します。

job が実行される前にレンダリングが終了した場合、ジョブは実行された後、シーングラフのクリーンアップの一環として削除されます。ウィンドウが一度も表示されず、QQuickWindow が破棄される前にレンダリングが行われなかった場合、保留中のすべてのジョブは、run() メソッドが呼び出されることなく破棄されます。

レンダリングが別のスレッドで行われている場合、そのジョブはレンダリングスレッド上で実行されます。

stage がNoStage の場合、job は、レンダリングスレッドがフレームのレンダリングで忙しくない最初の機会に行われます。ジョブが投稿または処理される時点で、ウィンドウが公開されておらず、かつレンダリング可能でない場合、ジョブはrun()メソッドが実行されることなく削除されます。 スレッド化されていないレンダラーが使用されている場合、ジョブの run() メソッドは同期的実行されます。OpenGL を使用してレンダリングを行う場合、NoStage ジョブを含むすべてのジョブを実行する前に、OpenGL コンテキストがレンダラーのコンテキストに変更されます。

関連項目： beforeRendering()、afterRendering()、beforeSynchronizing()、afterSynchronizing()、frameSwapped()、およびsceneGraphInvalidated()も参照してください 。

[static] void QQuickWindow::setDefaultAlphaBuffer(bool useAlpha)

useAlpha 新しく作成されるウィンドウでアルファ透過を使用するかどうかを指定します。

半透明のウィンドウを作成する予定のアプリケーションでは、最初のQQuickWindow を作成する前に、この値をtrueに設定する必要があります。デフォルト値はfalseです。

hasDefaultAlphaBuffer()も参照してください 。

[static, since 6.0] void QQuickWindow::setGraphicsApi(QSGRendererInterface::GraphicsApi api)

指定されたグラフィックスapi を要求します。

組み込みのデフォルトのグラフィックス適応が使用される場合、api は、シーングラフがレンダリングに使用するグラフィックス API（OpenGL、Vulkan、Metal、または Direct3D）を指定します。さらに、software バックエンドも組み込まれており、api をQSGRendererInterface::Software に設定することで要求できます。

特定のバックエンド（組み込みまたは動的に読み込まれるプラグインとしてインストールされたもの）を要求するためにのみ使用できるsetSceneGraphBackend() とは異なり、この関数はグラフィックス API というより高レベルの概念に基づいて動作します。この関数は、Qt Quick に同梱されているバックエンドを網羅しており、したがってQSGRendererInterface::GraphicsApi 列挙型に対応する値を持っています。

この関数がまったく呼び出されず、かつ同等の環境変数QSG_RHI_BACKEND も設定されていない場合、シーングラフはプラットフォームに基づいて使用するグラフィックスAPIを選択します。

この関数は、特定のAPIでのレンダリングにのみ対応しているアプリケーションにおいて重要になります。例えば、アプリケーションがネイティブなOpenGLやVulkanによるレンダリングを行う場合、Qt Quick もOpenGLまたはVulkanを使用してレンダリングされるようにする必要があります。このようなアプリケーションでは、main()関数の早い段階でこの関数を呼び出すことが期待されます。

シーングラフがレンダリングに使用しているグラフィックス API を確認するには、シーングラフの `has initialized` の後に `QSGRendererInterface::graphicsApi()` を呼び出します。これは通常、ウィンドウが最初に表示されたとき、または `QQuickRenderControl::initialize()` が呼び出されたときに発生します。

シーングラフがプラットフォームやその他の条件に基づいてグラフィックス API を選択するデフォルトの動作に戻すには、api をQSGRendererInterface::Unknown に設定します。

この関数は Qt 6.0 で導入されました。

graphicsApi()も参照してください 。

[since 6.0] void QQuickWindow::setGraphicsConfiguration(const QQuickGraphicsConfiguration &config)

このウィンドウのグラフィックス設定を指定します。`config ` には、基盤となるグラフィックスデバイスやコンテキストを初期化する際に、シーングラフが参照する可能性のあるさまざまな設定が含まれています。

たとえば、Vulkan で有効にするデバイス拡張機能を指定するといった追加の設定は、特定の拡張機能に依存するネイティブのグラフィックスレンダリングコードを統合する際に重要かつ不可欠となります。OpenXR などの外部 3D または VR エンジンと統合する場合も同様です。

QQuickGraphicsConfiguration インスタンスは暗黙的に共有され、コピー可能であり、値渡しで渡すことができます。

この関数は Qt 6.0 で導入されました。

graphicsConfiguration()も参照してください 。

[since 6.0] void QQuickWindow::setGraphicsDevice(const QQuickGraphicsDevice &device)

このウィンドウのグラフィックスデバイスオブジェクトを設定します。シーングラフは、新しいオブジェクトを作成する代わりに、device で指定された既存のデバイス、物理デバイス、およびその他のオブジェクトを使用します。

この関数は、`Qt Quick `のレンダリングをテクスチャにリダイレクトするために、`QQuickRenderControl `や`setRenderTarget()`と組み合わせて使用されることが非常に多い。

デフォルトで生成されたQQuickGraphicsDevice は、デフォルトの挙動を一切変更しません。QQuickGraphicsDevice::fromDeviceObjects()などのQQuickGraphicsDevice ファクトリ関数のいずれかを通じて作成されたdevice が渡され、シーングラフが対応するグラフィックスAPI（fromDeviceObjects()の例ではVulkan）を使用する場合、 シーングラフは、QQuickGraphicsDevice によってカプセル化された既存のデバイスオブジェクト（Vulkanの場合、VkPhysicalDevice 、VkDevice 、およびグラフィックスキューファミリーインデックスなど）を使用します。これにより、同じデバイスを使用できるようになり、Qt Quick とネイティブレンダリングエンジン間で、バッファやテクスチャなどのリソースを共有することが可能になります。

例として、今回は Direct3D を使用する場合、一般的な使用方法は以下の通りになると予想されます：

// native graphics resources set up by a custom D3D rendering engine
ID3D11Device *device;
ID3D11DeviceContext *context;
ID3D11Texture2D *texture;
...
// now to redirect Qt Quick content into 'texture' we could do the following:
QQuickRenderControl *renderControl = new QQuickRenderControl;
QQuickWindow *window = new QQuickWindow(renderControl); // this window will never be shown on-screen
...
window->setGraphicsDevice(QQuickGraphicsDevice::fromDeviceAndContext(device, context));
renderControl->initialize();
window->setRenderTarget(QQuickRenderTarget::fromD3D11Texture(texture, textureSize);
...

この関数を使用する際の重要な点は、リソース、あるいはリソースへのハンドル（上記の例ではtexture ）が、外部レンダリングエンジンとシーングラフレンダラーの両方から参照可能かつ使用可能であることを確保することです。これには、同じグラフィックスデバイス（または OpenGL の場合は OpenGL コンテキスト）を使用する必要があります。

QQuickGraphicsDevice インスタンスは暗黙的に共有され、コピー可能であり、値渡しで渡すことができます。インスタンスは、関連付けられたネイティブオブジェクト（例：例中の ID3D11Device）を所有するものではありません。

この関数は Qt 6.0 で導入されました。

関連項目： graphicsDevice()、QQuickRenderControl 、setRenderTarget()、およびsetGraphicsApi()。

void QQuickWindow::setPersistentGraphics(bool persistent)

persistent に対して、グラフィックスリソース（グラフィックスデバイスまたはコンテキスト、スワップチェーン、バッファ、テクスチャ）を保持し、最後のウィンドウが削除されるまで解放できないようにするかどうかを設定します。デフォルト値は true です。

releaseResources() を呼び出したとき、またはウィンドウが非表示になったとき（より具体的には、レンダリング不可能になったとき）、一部のレンダリングループでは、キャッシュされたものだけでなく、すべてのグラフィックスリソースを解放する可能性があります。 これにより一時的にメモリを解放できますが、ウィンドウが再びレンダリングが必要になった際、レンダリングエンジンはリソースの完全な再初期化を行わなければならず、その処理には多大なコストがかかる可能性があります。

関連項目： isPersistentGraphics()、setPersistentSceneGraph()、sceneGraphInitialized()、sceneGraphInvalidated()、およびreleaseResources()。

void QQuickWindow::setPersistentSceneGraph(bool persistent)

シーングラフノードおよびリソースがpersistent であるかどうかを設定します。「Persistent」は、ノードおよびリソースが解放できないことを意味します。デフォルト値はtrue です。

releaseResources() を呼び出した際、ウィンドウが非表示（より具体的には、レンダリング不可）になると、一部のレンダリングループではシーングラフノードおよび関連するグラフィックリソースを解放する可能性があります。これにより一時的にメモリが解放されますが、次回ウィンドウがレンダリングされる際にシーングラフを再構築する必要が生じます。

関連項目: isPersistentSceneGraph()、setPersistentGraphics()、sceneGraphInvalidated()、sceneGraphInitialized()、およびreleaseResources()。

[since 6.0] void QQuickWindow::setRenderTarget(const QQuickRenderTarget &target)

このウィンドウのレンダリングターゲットを `target` に設定します。

QQuickRenderTarget は、レンダリング可能なネイティブオブジェクト（最も一般的なのは2Dテクスチャ）およびピクセル単位のサイズなどの関連メタデータに対する不透明なハンドルとして機能します。

デフォルトで生成された `QQuickRenderTarget ` は、リダイレクトを行いません。一方、静的ファクトリ関数 `QQuickRenderTarget ` のいずれかを使用して作成された有効な `target` は、Qt Quick シーンのレンダリングのリダイレクトを可能にします。これにより、レンダリング先はウィンドウに関連付けられたサーフェスのカラーバッファではなく、`target` で指定されたテクスチャやその他のグラフィックスオブジェクトになります。

たとえば、シーングラフが Vulkan を使用してレンダリングしていると仮定すると、その出力をVkImage にリダイレクトすることができます。Vulkan のようなグラフィックス API の場合、画像レイアウトも指定する必要があります。QQuickRenderTarget インスタンスは暗黙的に共有され、コピー可能であり、値渡しで渡すことができます。 ただし、それらは関連するネイティブオブジェクト（例：この例での VkImage）を所有しているわけではありません。

QQuickRenderTarget rt = QQuickRenderTarget::fromVulkanImage(vulkanImage, VK_IMAGE_LAYOUT_PREINITIALIZED, pixelSize);
quickWindow->setRenderTarget(rt);

この関数は、QQuickRenderControl および非表示のQQuickWindow と組み合わせて使用されることが非常に多く、このQQuickWindow 用の画面上のネイティブウィンドウを作成することなく、Qt Quick のコンテンツをテクスチャにレンダリングするために使用されます。

目的のターゲットや、サイズなどの関連データが変更された場合は、新しい `QQuickRenderTarget` を指定してこの関数を呼び出してください。`QQuickRenderTarget ` インスタンスの構築やこの関数の呼び出しはコストが低いですが、異なるネイティブオブジェクトやその他のデータを含む新しい `target ` を設定すると、シーングラフが次のフレームをレンダリングしようとする際に、コストのかかる初期化処理が発生する可能性があることに注意してください。 したがって、ターゲットの変更は必要な場合にのみ行ってください。

この関数は Qt 6.0 で導入されました。

関連項目： renderTarget()、QQuickRenderControl 、setGraphicsDevice()、およびsetGraphicsApi()。

[static] void QQuickWindow::setSceneGraphBackend(const QString &backend)

Qt Quick のシーングラフをbackend から取得します。バックエンドは、組み込みのものか、動的に読み込まれるプラグインとしてインストールされたもののいずれかになります。

バックエンドの一覧に関する詳細については、「アプリケーションでのアダプテーションの切り替え」を参照してください。backend が無効である場合やエラーが発生した場合は、リクエストは無視されます。

関連項目: sceneGraphBackend().

[static] void QQuickWindow::setTextRenderType(QQuickWindow::TextRenderType renderType)

Qt Quick 内のテキストのような要素のデフォルトのレンダリングタイプを、renderType に設定します。

textRenderType()も参照してください 。

[override virtual protected] void QQuickWindow::showEvent(QShowEvent *)

QWindow::showEvent(QShowEvent *ev) の再実装。

[since 6.6] QRhiSwapChain *QQuickWindow::swapChain() const

このウィンドウで使用されているQRhiSwapChain （存在する場合）を返します。

この関数は Qt 6.6 で導入されました。

[override virtual protected] void QQuickWindow::tabletEvent(QTabletEvent *event)

QWindow::tabletEvent(QTabletEvent *ev) を再実装します。

[static] QQuickWindow::TextRenderType QQuickWindow::textRenderType()

Qt Quick 内のテキストのような要素のレンダリングタイプを返します。デフォルトは `QQuickWindow::QtTextRendering` です。

setTextRenderType()も参照してください 。

[slot] void QQuickWindow::update()

ウィンドウに対して、次のフレームをレンダリングするようスケジュールします。

QQuickWindow::update() の呼び出しは、QQuickItem::update() とは異なり、基になるシーングラフに変更があるかどうかに関わらず、常に再描画をトリガーします。

[override virtual protected] void QQuickWindow::wheelEvent(QWheelEvent *event)

QWindow::wheelEvent(QWheelEvent *ev) を再実装します。