Back to Qt.io
Contact Us Blog Download Qt

Canvas QML Type

JavaScript による描画を可能にする 2D canvas アイテムを提供します。詳細...

Import Statement: import QtQuick
Inherits:

Item

プロパティ

信号

方法

詳細説明

Canvas アイテムでは、直線や曲線、単純な図形や複雑な図形、グラフ、参照されるグラフィック画像を描画できます。また、テキスト、色、影、グラデーション、パターンを追加したり、低レベルのピクセル操作を行うこともできます。キャンバスの出力は、画像ファイルとして保存することも、URLにシリアライズすることもできます。

Canvasへのレンダリングは、通常paint 信号の結果として、Context2D オブジェクトを使用して行われます。

Canvasアイテムに描画領域を定義するには、width とheight プロパティを設定します。例えば、次のコードは、高さ 100 ピクセル、幅 200 ピクセルの描画領域を持つ Canvas アイテムを作成します：

import QtQuick 2.0
Canvas {
    id: mycanvas
    width: 100
    height: 200
    onPaint: {
        var ctx = getContext("2d");
        ctx.fillStyle = Qt.rgba(1, 0, 0, 1);
        ctx.fillRect(0, 0, width, height);
    }
}

現在、Canvas アイテムは 2 次元のレンダリング コンテキストのみをサポートしています。

スレッドレンダリングとレンダーターゲット

Qt 6.0 では、Canvas アイテムは 1 つのレンダーターゲットCanvas.Image をサポートしています。

Canvas.Image レンダー ターゲットはQImage オブジェクトです。このレンダー ターゲットはバックグラウンド スレッド レンダリングをサポートし、複雑な描画や長時間実行される描画を UI をブロックせずに実行できます。これは、すべてのQt Quick バックエンドでサポートされている唯一のレンダーターゲットです。

デフォルトのレンダーターゲットはCanvas.Imageで、デフォルトのrenderStrategy はCanvas.Immediateです。

ピクセル操作

すべての HTML5 2D コンテキスト ピクセル操作がサポートされています。ピクセルの読み取り/書き込みのパフォーマンスを確実に向上させるには、Canvas.Image レンダー ターゲットを選択する必要があります。

既存の HTML5 Canvas アプリケーションを移植するためのヒント

Canvas アイテムは HTML5 ライクな API を提供しますが、HTML5 canvas アプリケーションを Canvas アイテムで実行するように変更する必要があります：

  • すべての DOM API 呼び出しを QML プロパティバインディングまたは Canvas アイテムメソッドに置き換えます。
  • すべての HTML イベントハンドラをMouseArea アイテムに置き換える。
  • setInterval/setTimeout 関数呼び出しをTimer アイテムまたはrequestAnimationFrame() の使用に変更する。
  • 描画コードをonPaint ハンドラに置き、markDirty() またはrequestPaint() メソッドを呼び出して描画をトリガーします。
  • 画像を描画するには、Canvas のloadImage() メソッドを呼び出して画像を読み込み、onImageLoaded ハンドラで描画を要求します。

Qt 5.4 以降、Canvas はtexture provider であり、ShaderEffects や、テクスチャ・プロバイダを消費する他のクラスで直接使用することができます。

注： 一般的に、大きなキャンバス、頻繁な更新、アニメーションは、Canvas.Image レンダー ターゲットでは避けるべきです。加速されたグラフィックスAPIでは、更新のたびにテクスチャがアップロードされるからです。また、可能であれば、QQuickPaintedItem 、JavaScriptやContext2D 、よりコストがかかり、パフォーマンスが低下する可能性が高い代わりに、QPainter 、C++で描画を実装することをお勧めします。

Context2D 、QQuickPaintedItem 、Qt Quick Examples - Pointer Handlersも参照してください 。

プロパティ ドキュメント

available : bool [read-only]

Canvas が操作する描画コンテキストを提供できるときを示します。


canvasSize : size

コンテキストが描画する論理的なキャンバスサイズを保持します。

デフォルトでは、キャンバスのサイズは現在のキャンバスアイテムのサイズと同じです。

canvasSize、tileSize、canvasWindow を設定することで、Canvas アイテムは、個別にレンダリングされた多数のタイル矩形を持つ大きな仮想キャンバスとして動作することができます。キャンバスのレンダリング エンジンによって描画されるのは、現在のキャンバス ウィンドウ内のタイルだけです。

tileSize およびcanvasWindowも参照してください 。


context : object [read-only]

アクティブな描画コンテキストを保持します。

canvasの準備ができていて、getContext （）の呼び出しが成功したか、contextType プロパティにサポートされているコンテキストタイプが設定されている場合、このプロパティには現在の描画コンテキストが格納され、そうでない場合は null になります。


contextType : string

使用する描画コンテキストのタイプ。

このプロパティは、アクティブなコンテキストタイプの名前に設定されます。

明示的に設定された場合、canvas は利用可能になった後、指定された型のコンテキストを作成しようとします。

型名はgetContext() で使用したものと同じです。2d canvas の場合、値は "2d" になります。

getContext() およびavailableも参照して ください。


renderStrategy : enumeration

現在のキャンバスのレンダリング戦略を保持します。

定数説明
Canvas.Immediatecontext は、メイン UI スレッドでグラフィックコマンドを即座に実行します。
Canvas.Threadedコンテキストは、グラフィックコマンドをプライベートレンダリングスレッドに延期します。
Canvas.Cooperativeコンテキストは、グラフィックスコマンドをアプリケーションのグローバルレンダリングスレッドに延期します。

このヒントは、renderTarget とともにグラフィックコンテキストに供給され、レンダリングの方法を決定します。renderStrategy、renderTarget 、またはその組み合わせは、グラフィックコンテキストによってサポートされていない場合があります。その場合、コンテキストは適切なオプションを選択し、Canvasはプロパティに変更を通知します。

コンフィギュレーションやランタイムテストによって、QMLシーングラフがGUIスレッドでレンダリングされる場合があります。Canvas.Cooperative を選択しても、GUI スレッドとは別のスレッドでレンダリングが行われることは保証されません。

デフォルト値はCanvas.Immediate です。

renderTargetも参照してください 。


renderTarget : enumeration

現在のキャンバスのレンダリングターゲットを保持します。

定数説明
Canvas.Imageメモリ内の画像バッファにレンダリングします。
Canvas.FramebufferObjectQt 6.0 では、この値は無視されます。

このヒントは、renderStrategy と共にグラフィックコンテキストに供給され、レンダリングの方法を決定します。renderStrategyその場合、コンテキストは適切なオプションを選択し、Canvasはプロパティに変更を通知します。

デフォルトのレンダーターゲットはCanvas.Image です。


シグナルの説明

imageLoaded()

このシグナルは、画像が読み込まれたときに発行されます。

注意： 対応するハンドラはonImageLoaded です。

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


paint(rect region)

このシグナルは、region のレンダリングが必要になったときに発せられます。コンテキストがアクティブな場合は、contextプロパティから参照できます。

このシグナルは、markDirty()、requestPaint()、または現在の canvas ウィンドウを変更することによってトリガされます。

注： 対応するハンドラはonPaint です。


painted()

このシグナルは、すべてのコンテキストペインティングコマンドが実行され、キャンバスがレンダリングされた後に発行されます。

注意 ：対応するハンドラはonPainted です。


メソッドの説明

cancelRequestAnimationFrame(int handle)

この関数は、handle によって参照されるアニメーション コールバックをキャンセルします。


object getContext(string contextId, ... args)

描画コンテキストを返し、コンテキストがない場合はnull を返します。

contextId パラメータには、必要なコンテキスト名を指定します。Canvas 項目は、必要な描画モードを実装するコンテキストを返します。getContext を最初に呼び出した後、同じ contextId で getContext を呼び出すと、同じコンテキストオブジェクトが返されます。追加引数 (args) は現在のところ無視されます。

コンテキストタイプがサポートされていない場合、または canvas が以前に互換性のない別のコンテキストタイプを要求されたことがある場合は、null が返されます。

Canvas は 2d コンテキストしかサポートしていません。


isImageError(url image)

image の読み込みに失敗した場合はtrue を返し、そうでない場合はfalse を返します。

loadImage()も参照 。


isImageLoaded(url image)

image の読み込みに成功し、使用できる状態になった場合は true を返します。

loadImage()も参照 。


isImageLoading(url image)

image が現在ロード中であれば true を返す。

loadImage()も参照 。


loadImage(url image, size sourceSize = undefined)

与えられたimage を非同期に読み込みます。

画像の準備ができると、imageLoaded() シグナルが発せられます。読み込まれた画像は、unloadImage() メソッドでアンロードできます。

注意: Canvasアイテムに描画できるのは、ロードされた画像のみです。

sourceSize が指定された場合、画像はロード中にそのサイズに拡大縮小されます。これは、スケーラブルな（ベクトル）画像（SVG など）を意図した表示サイズで読み込む場合に便利です。このパラメータは Qt 6.7 で導入されました。

unloadImage(),imageLoaded(),isImageLoaded(),Context2D::createImageData(),Context2D::drawImage()も参照してください 。


markDirty(rect area)

指定されたarea をダーティとしてマークし、この領域が表示されているときに canvas レンダラーが再描画するようにします。これによりpaint シグナルがトリガされます。

paint およびrequestPaint()も参照してください 。


int requestAnimationFrame(callback)

この関数は、Qt Quick シーンを構成する前に呼び出されるcallback をスケジュールします。


requestPaint()

可視領域全体の再描画を要求する。

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


bool save(string filename, size imageSize = undefined)

現在のキャンバスの内容を画像ファイルfilename に保存します。保存される画像フォーマットはfilename のサフィックスによって自動的に決定されます。成功するとtrue を返します。imageSize が指定されている場合、結果の画像はこのサイズになり、devicePixelRatio は1.0 になります。 そうでない場合、canvas が表示されているウィンドウのdevicePixelRatio() が、保存された画像に適用されます。

注意： このメソッドを呼び出すと、現在のキャンバスが表示されているウィンドウだけでなく、キャンバス全体が強制的に描画されます。

canvasWindow 、canvasSize 、toDataURL()も参照してください 。


string toDataURL(string mimeType)

キャンバス内の画像のデータ URL を返します。

デフォルトのmimeType は "image/png" です。

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


unloadImage(url image)

image をアンロードします。

一度アンロードされた画像は、再度読み込まれない限り canvas コンテキストで描画することはできません。

loadImage()、imageLoaded()、isImageLoaded()、Context2D::createImageData() およびContext2D::drawImage も参照 。


© 2025 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.