Canvas QML Type

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

• 継承されたメンバーを含む、すべてのメンバーの一覧
• 非推奨のメンバー

プロパティ

• available : bool
• canvasSize : size
• context : object
• contextType : string
• renderStrategy : enumeration
• renderTarget : enumeration

信号

• imageLoaded()
• paint(rect region)
• painted()

方法

• void cancelRequestAnimationFrame(int handle)
• Context2D getContext(string contextId, ... args)
• bool isImageError(url image)
• bool isImageLoaded(url image)
• bool isImageLoading(url image)
• void loadImage(url image, size sourceSize)
• void markDirty(rect area)
• int requestAnimationFrame(callback)
• void requestPaint()
• bool save(string filename, size imageSize)
• string toDataURL(string mimeType)
• void unloadImage(url image)

詳細説明

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

Canvasへの描画は、Context2D オブジェクトを使用して行われ、通常はpaint シグナルの結果として実行されます。

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 や、テクスチャプロバイダを利用するその他のクラスで直接使用できます。

Context2D 、QQuickPaintedItem 、およびQt Quick の「例 - ポインタハンドラ」も参照してください 。

プロパティのドキュメント

available : bool [read-only]

Canvas が操作対象となる描画コンテキストを提供できる状態であることを示します。

canvasSize : size

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

デフォルトでは、キャンバスのサイズは現在のキャンバス項目のサイズと同じになります。

canvasSize、tileSize、および canvasWindow を設定することで、Canvas アイテムは、個別にレンダリングされる多数のタイル矩形からなる大きな仮想キャンバスとして機能します。Canvas レンダリングエンジンによって描画されるのは、現在のキャンバスウィンドウ内にあるタイルのみです。

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

context : object [read-only]

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

キャンバスが準備完了状態で、getContext() の呼び出しが成功しているか、contextType プロパティがサポートされているコンテキストタイプで設定されている場合、このプロパティには現在の描画コンテキストが含まれます。それ以外の場合は null になります。

contextType : string

使用する描画コンテキストの種類。

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

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

タイプ名は、getContext() の呼び出しで使用されるものと同じです。2D キャンバスの場合、値は「2d」になります。

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

renderStrategy : enumeration

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

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

設定や実行時のテストにより、QML シーングラフが GUI スレッドでレンダリングされる場合があります。Canvas.Cooperative を選択しても、GUI スレッドとは別のスレッドでレンダリングが行われることが保証されるわけではありません。

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

「renderTarget」も参照してください 。

renderTarget : enumeration

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

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

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

Signal ドキュメント

imageLoaded()

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

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

paint(rect region)

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

このシグナルは、markDirty()、requestPaint()、または現在のキャンバスウィンドウの変更によってトリガーされる可能性があります。

painted()

このシグナルは、すべてのコンテキスト描画コマンドが実行され、Canvas のレンダリングが完了した後に発火します。

メソッドのドキュメント

void cancelRequestAnimationFrame(int handle)

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

Context2D getContext(string contextId, ... args)

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

contextId パラメータは、必要なコンテキストを指定します。Canvas アイテムは、指定された描画モードを実装するコンテキストを返します。getContext の最初の呼び出し後、同じ contextId を使用して getContext を再度呼び出すと、同じコンテキストオブジェクトが返されます。追加の引数（args ）は、現時点では無視されます。

コンテキストのタイプがサポートされていない場合、または以前にキャンバスに対して互換性のない別のコンテキストタイプの提供が要求されていた場合、null が返されます。

Canvasは2Dコンテキストのみをサポートしています。

bool isImageError(url image)

image の読み込みに失敗した場合はtrue を返し、それ以外の場合はfalse を返します。

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

bool isImageLoaded(url image)

image が正常に読み込まれ、使用可能な状態であれば、true を返します。

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

bool isImageLoading(url image)

image が現在読み込み中の場合、true を返します。

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

void loadImage(url image, size sourceSize = undefined)

指定されたimage を非同期で読み込みます。

画像の準備が完了すると、imageLoaded() シグナルが発行されます。読み込まれた画像は、unloadImage() メソッドを使用してアンロードできます。

sourceSize が指定されている場合、読み込み中に画像はそのサイズにスケーリングされます。これは、スケーラブルな（ベクター）画像（例：SVG）を意図した表示サイズで読み込む際に役立ちます。このパラメータはQt 6.7で導入されました。

関連項目： unloadImage()、imageLoaded()、isImageLoaded()、Context2D::createImageData()、およびContext2D::drawImage()。

void markDirty(rect area)

指定されたarea を「変更済み」としてマークし、この領域が表示されている際にキャンバスレンダラーが再描画を行うようにします。これにより、paint シグナルがトリガーされます。

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

int requestAnimationFrame(callback)

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

void requestPaint()

表示領域全体を再描画するように要求します。

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

bool save(string filename, size imageSize = undefined)

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

関連項目： canvasWindow 、canvasSize 、およびtoDataURL()。

string toDataURL(string mimeType)

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

mimeType のデフォルト値は「image/png」です。

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

void unloadImage(url image)

image をアンロードします。

一度アンロードされた画像は、再度ロードされない限り、キャンバスコンテキストによって描画されることはありません。

loadImage()、imageLoaded()、isImageLoaded()、Context2D::createImageData() およびContext2D::drawImageも参照してください 。