Image QML Type

画像を表示します。詳細...

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

プロパティ

• asynchronous : bool
• autoTransform : bool
• cache : bool
• currentFrame : int
• fillMode : enumeration
• frameCount : int
• horizontalAlignment : enumeration
• mipmap : bool
• mirror : bool
• mirrorVertically : bool (since 6.2)
• paintedHeight : real
• paintedWidth : real
• progress : real
• retainWhileLoading : bool (since 6.8)
• smooth : bool
• source : url
• sourceClipRect : rect
• sourceSize : size
• status : enumeration
• verticalAlignment : enumeration

詳細説明

Image タイプは画像を表示します。

画像のソースは、source プロパティを使用して URL として指定します。画像は、PNG や JPEG などのビットマップ形式、SVG などのベクターグラフィックス形式を含め、Qt がサポートする標準的な画像形式であればどれでも指定できます。アニメーション画像を表示する必要がある場合は、AnimatedSprite またはAnimatedImage を使用してください。

width およびheight プロパティが指定されていない場合、Image は読み込まれた画像のサイズを自動的に使用します。デフォルトでは、項目の幅と高さを指定すると、画像はそのサイズに合わせてスケーリングされます。この動作は、fillMode プロパティを設定することで変更でき、代わりに画像を伸縮させたりタイル状に並べたりすることができます。

"@nx" high DPI syntax を指定することも可能です。

使用例

以下の例は、Image 型の最も単純な使用例を示しています。

import QtQuick

Image {
    source: "pics/qtlogo.png"
}

圧縮テクスチャファイル

実行時に基盤となるグラフィックスAPIの実装がサポートしている場合、画像は圧縮されたテクスチャファイルとして指定することもできます。コンテンツは、単純なRGB(A)形式の2Dテクスチャでなければなりません。サポートされる圧縮方式は、基盤となるドライバおよびGPUによってのみ制限されます。以下のコンテナファイル形式がサポートされています：

• PKM (Qt 5.10 以降)
• KTX (Qt 5.11 以降)
• ASTC (Qt 5.13 以降)

transform: [ Translate { y: -myImage.height }, Scale { yScale: -1 } ]

または

mirrorVertically: true

convert foo.png \( +clone -alpha Extract \) -channel RGB -compose Multiply -composite foo_pm.png

KTX などのコンテナ形式と、コンテナファイル内に格納されている実際のテクスチャデータの形式を混同しないでください。たとえば、KTX ファイルの読み込みは、実行時にどの GPU ドライバーが使用されているかに関係なく、すべてのプラットフォームでサポートされています。しかし、これによって、ファイル内のデータで使用されている圧縮テクスチャ形式が実行時にサポートされていることが保証されるわけではありません。 たとえば、KTX ファイルにETC2 RGBA8 形式の圧縮データが含まれており、実行時に使用される 3D グラフィックス API の実装がETC2 の圧縮テクスチャをサポートしていない場合、Image アイテムには何も表示されません。

圧縮形式のサポートが特定のプラットフォームに固有であると想定しないでください。また、その特定のプラットフォームで使用されているドライバや 3D API の実装に固有である可能性もあります。 実際には、同じハードウェアに対して同じベンダーが提供する同一プラットフォーム（Windows など）上の異なる 3D グラフィックス API（Vulkan や OpenGL など）の実装では、サポートされる圧縮テクスチャ形式が異なる場合があります。

デスクトップ環境（Windows、macOS、Linux）のみを対象とする場合、一般的な推奨事項として、DXTn/BCn フォーマットの使用を検討することをお勧めします。これらのフォーマットは、これらのプラットフォーム上の Direct 3D、Vulkan、OpenGL、および Metal の実装において、最も広くサポートされている傾向があるからです。 対照的に、モバイルや組み込みデバイスをターゲットとする場合は、ETC2 またはASTC 形式の方が適している可能性が高いです。これらは通常、そのようなハードウェア上の OpenGL ES 実装でサポートされている形式だからです。

デスクトップ、モバイル、組み込みハードウェアのすべてで動作させることを意図したアプリケーションでは、圧縮テクスチャの使用について慎重に計画・設計する必要があります。 単一のフォーマットに依存するだけでは不十分である可能性が非常に高いため、アプリケーションでは、プラットフォームに応じて分岐処理を行い、そのプラットフォームに適したフォーマットで圧縮テクスチャを使用するか、場合によっては圧縮テクスチャの使用をスキップする必要があるでしょう。

ファイル拡張子の自動検出

source URL が存在しないローカルファイルまたはリソースを指している場合、Image 要素はファイル拡張子を自動検出しようとします。source URL にサポートされている画像ファイル拡張子のいずれかを付加することで既存のファイルが見つかった場合、そのファイルが読み込まれます。

ファイル検索では、まず圧縮テクスチャコンテナファイルの拡張子を優先して検索します。検索に失敗した場合は、conventional image file types に指定されたファイル拡張子で検索を試みます。例：

// Assuming the "pics" directory contains the following files:
//   dog.jpg
//   cat.png
//   cat.pkm

Image {
    source: "pics/cat.png"     // loads cat.png
}

Image {
    source: "pics/dog"         // loads dog.jpg
}

Image {
    source: "pics/cat"         // normally loads cat.pkm, but if no OpenGL, loads cat.png instead.
}

この機能により、異なるターゲットプラットフォーム上で異なる種類の画像アセットファイルを展開することが容易になります。これは、アプリケーションのパフォーマンスを最適化したり、さまざまなグラフィックスハードウェアに対応したりする際に役立ちます。

この機能は Qt 5.11 で導入されました。

パフォーマンス

デフォルトでは、ローカルにある画像は即座に読み込まれ、読み込みが完了するまでユーザーインターフェースはブロックされます。大きな画像を読み込む場合は、asynchronous プロパティを有効にして、低優先度のスレッドで画像を読み込む方が望ましい場合があります。

画像がローカルリソースではなくネットワークから取得される場合、自動的に非同期で読み込まれ、progress およびstatus プロパティは適宜更新されます。

画像は内部でキャッシュされ、共有されるため、複数の Image アイテムが同じsource を持つ場合、その画像のコピーは 1 つだけ読み込まれます。

注：QML ユーザーインターフェースにおいて、画像は多くの場合、メモリを最も多く消費する要素です。ユーザーインターフェースの一部を構成しない画像については、sourceSize プロパティを使用してサイズを制限することをお勧めします。これは、外部ソースから読み込まれるコンテンツやユーザーによって提供されるコンテンツにおいて特に重要です。

「 Qt Quick の例 - 画像要素」（QQuickImageProvider ）および「QImageReader::setAutoDetectImageFormat()」も参照してください 。

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

asynchronous : bool

ローカルファイルシステム上の画像を、別のスレッドで非同期に読み込むように指定します。デフォルト値は false であり、この場合、画像の読み込み中はユーザーインターフェースのスレッドがブロックされます。asynchronous を true に設定すると、画像を即座に表示させることよりも、ユーザーインターフェースの応答性を維持することが望ましい場合に役立ちます。

なお、このプロパティはローカルファイルシステムから読み込まれる画像にのみ有効です。ネットワークリソース（HTTP など）経由で読み込まれる画像は、常に非同期で読み込まれます。

autoTransform : bool

このプロパティは、画像に対してEXIFの向きなどの画像変換メタデータを自動的に適用するかどうかを指定します。

デフォルトでは、このプロパティは false に設定されています。

cache : bool

画像をキャッシュするかどうかを指定します。デフォルト値は true です。cache を false に設定すると、大きな画像を扱う際に、小さな「UI 要素」の画像のキャッシュを犠牲にしてまで大きな画像がキャッシュされないようにするのに役立ちます。

currentFrame 現在表示されているフレームです。デフォルトは0 です。画像に複数のフレームが含まれている場合、0 からframeCount - 1 までの範囲の数値を設定することで、別のフレームを表示することができます。

frameCount は、画像に含まれるフレームの数です。ほとんどの画像にはフレームが1つしか含まれていません。

fillMode : enumeration

このプロパティを設定することで、ソース画像のサイズがアイテムのサイズと異なる場合の動作を定義します。

Image {
    width: 130; height: 100
    source: "qtlogo.png"
}

Image {
    width: 130; height: 100
    fillMode: Image.PreserveAspectFit
    source: "qtlogo.png"
}

Image {
    width: 130; height: 100
    fillMode: Image.PreserveAspectCrop
    source: "qtlogo.png"
    clip: true
}

Image {
    width: 120; height: 120
    fillMode: Image.Tile
    horizontalAlignment: Image.AlignLeft
    verticalAlignment: Image.AlignTop
    source: "qtlogo.png"
}

Image {
    width: 120; height: 120
    fillMode: Image.TileVertically
    verticalAlignment: Image.AlignTop
    source: "qtlogo.png"
}

Image {
    width: 120; height: 120
    fillMode: Image.TileHorizontally
    verticalAlignment: Image.AlignLeft
    source: "qtlogo.png"
}

なお、clip はデフォルトでfalse に設定されているため、fillModeがPreserveAspectCrop に設定されている場合でも、アイテムがバウンディング矩形の外側に描画される可能性があります。

「Qt Quick の例 - 画像要素」も参照してください 。

画像の水平および垂直方向の配置を設定します。デフォルトでは、画像は中央揃えになります。

horizontalAlignment の有効な値は、Image.AlignLeft 、Image.AlignRight 、Image.AlignHCenter です。verticalAlignment の有効な値は、Image.AlignTop 、Image.AlignBottom 、Image.AlignVCenter です。

mipmap : bool

このプロパティは、画像の拡大・縮小や変形時にミップマップフィルタリングが使用されるかどうかにかかわらず有効です。

ミップマップフィルタリングは、縮小時に「滑らか」設定と比較してより高い画質を実現しますが、パフォーマンスの低下を招く可能性があります（画像の初期化時およびレンダリング中の両方で）。

デフォルトでは、このプロパティは false に設定されています。

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

mirror : bool

このプロパティは、画像を水平反転させるかどうか（実質的に鏡像を表示するかどうか）を指定します。

デフォルト値は false です。

mirrorVertically : bool [since 6.2]

このプロパティは、画像を垂直反転させるかどうか（実質的に鏡像を表示するかどうか）を指定します。

デフォルト値は false です。

このプロパティは Qt 6.2 で導入されました。

これらのプロパティには、実際に描画される画像のサイズが格納されます。ほとんどの場合、これらは `width ` および `height` と同じですが、Image.PreserveAspectFit やImage.PreserveAspectCrop を使用する場合、paintedWidth やpaintedHeight は、Image 項目の `width ` や `height ` よりも小さくなったり大きくなったりすることがあります。

progress : real [read-only]

このプロパティは、画像の読み込み進捗状況を、0.0（読み込みなし）から1.0（完了）まで保持します。

statusも参照してください 。

retainWhileLoading : bool [since 6.8]

このプロパティは、source プロパティが変更され、読み込みが非同期で行われる場合の挙動を定義します。これは、asynchronous プロパティがtrue に設定されている場合、または画像がローカルファイルシステム上に存在しない場合に該当します。

retainWhileLoading がfalse （デフォルト）の場合、古い画像は直ちに破棄され、新しい画像の読み込み中はコンポーネントがクリアされます。true に設定された場合、古い画像は保持され、新しい画像の準備が整うまで表示されたままになります。

このプロパティを有効にすると、新しい画像の読み込みに時間がかかる場合に発生するちらつきを防ぐことができます。ただし、その代償として、新しい画像の読み込み中はダブルバッファリングのために余分なメモリが消費されます。

このプロパティは Qt 6.8 で導入されました。

smooth : bool

このプロパティは、画像の拡大・縮小や変形時にスムージング処理が行われるかどうかを指定します。スムージング処理を行うと視覚的な品質は向上しますが、一部のハードウェアでは処理速度が低下する場合があります。画像が本来のサイズで表示される場合、このプロパティは表示やパフォーマンスに影響を与えません。

デフォルトでは、このプロパティは true に設定されています。

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

source : url

Imageは、Qtがサポートするあらゆる画像形式に対応しており、QtがサポートするあらゆるURLスキーマから読み込むことができます。

URLは絶対パスでも、コンポーネントのURLを基準とした相対パスでも構いません。

QQuickImageProvider 、Compressed Texture Files 、およびAutomatic Detection of File Extensionも参照してください 。

sourceClipRect : rect

このプロパティを設定すると、読み込むソース画像の矩形領域が指定されます。

sourceClipRect は、sourceSize プロパティと連携して、画像の一部のみを読み込む必要がある場合にシステムリソースを節約します。

Rectangle {
    width: ...
    height: ...

    Image {
       anchors.fill: parent
       source: "reallyBigImage.svg"
       sourceSize.width: 1024
       sourceSize.height: 1024
       sourceClipRect: Qt.rect(100, 100, 512, 512)
    }
}

上記の例では、概念的にはまず SVG グラフィックを 1024x1024 に拡大し、次に、上端および左端から 100 ピクセルの位置にある 512x512 ピクセルの対象領域を切り抜きます。 したがって、sourceSize がスケールを決定しますが、実際の出力画像は512x512ピクセルになります。

一部の画像形式では、指定された領域のみをレンダリングすることで CPU 時間を節約できます。その他の形式では、まず画像全体を読み込み、その後、指定された領域にクリップする必要があります。

このプロパティをクリアし、sourceClipRect をundefined に設定することで、画像全体を再読み込みすることができます。

sourceSize : size

このプロパティには、フルフレーム画像の拡大・縮小後の幅と高さが格納されます。

画像の描画をスケーリングするwidth やheight プロパティとは異なり、このプロパティは読み込まれた画像に対して保存されるピクセル数の最大値を設定し、大きな画像が必要以上のメモリを使用しないようにします。たとえば、これにより、Imageのwidth やheight の値にかかわらず、メモリ内の画像のサイズが1024×1024ピクセルを超えないようにします。

Rectangle {
    width: ...
    height: ...

    Image {
       anchors.fill: parent
       source: "reallyBigImage.jpg"
       sourceSize.width: 1024
       sourceSize.height: 1024
    }
}

画像の実際のサイズが `sourceSize` より大きい場合、画像は縮小されます。サイズの片方の次元のみが 0 より大きい値に設定されている場合、もう一方の次元は、元の画像のアスペクト比を維持するように比例して設定されます（fillMode はこの設定とは独立しています）。

sourceSize.width と sourceSize.height の両方が設定されている場合、画像は指定されたサイズに収まるように縮小されます（PreserveAspectCrop または PreserveAspectFit が使用されている場合は、トリミング／フィットに最適なサイズに合わせてスケーリングされます）。この際、画像のアスペクト比は維持されます。 スケーリング後の画像の実際のサイズは、Item::implicitWidth およびItem::implicitHeight を通じて取得できます。

ソースが本質的にスケーラブルな画像（例：SVG）の場合、このプロパティは、本質的なサイズに関係なく、読み込まれる画像のサイズを決定します。このプロパティを動的に変更することは避けてください。SVG のレンダリングは、画像に比べて処理に時間がかかります。

ソースがスケーラブルでない画像（例：JPEG）の場合、読み込まれる画像のサイズは、このプロパティで指定された値を超えないものになります。一部の形式（現在は JPEG のみ）では、画像全体が実際にメモリに読み込まれることはありません。

sourceClipRect プロパティも設定されている場合、sourceSize によって拡大縮小率が決定されますが、クリップ矩形のサイズに合わせてトリミングされます。

sourceSizeをundefined に設定することで、sourceSizeを画像の元のサイズにリセットできます。

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

status : enumeration [read-only]

このプロパティは、画像の読み込み状態を表します。以下のいずれかの値をとります。

このステータスを利用して、最新情報を提供したり、ステータスの変更に対して何らかの対応を行ったりしてください。例えば、次のような対応が可能です:

• 状態の変更をトリガーする：

  State { name: 'loaded'; when: image.status == Image.Ready }

• onStatusChanged シグナルハンドラを実装する：

  Image {
      id: image
      onStatusChanged: if (image.status == Image.Ready) console.log('Loaded')
  }

• ステータス値にバインドする：

  Text { text: image.status == Image.Ready ? 'Loaded' : 'Not loaded' }

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