C

Qt Quick Ultralite sprite_animations の例

スプライトアニメーションの作成方法を示しています。

概要

sprite_animations のサンプルでは、画像ファイル内のフレームシーケンスからスプライトアニメーションを作成する方法を示しています。

画面中央にQtのロゴがアニメーション表示されるスプライトアニメーションの例です。画面左上にはフレーム番号と再生時間が表示され、右上には「無限ループ／1回のみ」を切り替えるトグルボタンがあります。

この例の画像ソースは16フレームで構成されており、各フレームのサイズは180x160です。

対象プラットフォーム

画像フォーマット

Qt Quick Ultralite を使用すると、デフォルトの代わりにハードウェア画像デコーダを使用できます。AnimatedSprite およびAnimatedSpriteDirectory の両方の QML タイプは、スプライトアニメーション用に登録された画像形式をサポートしています。

この例では、STM32F769i、STM32H750b、RH850/D1M1A 評価ボード、およびInfineon TRAVEO T2G CYT4DNボードでの画像デコーダのユースケースを示しています。これらのボードでは、プロジェクトで JPEG デコーダを設定し、ImageFilesノード内の JPEG ファイルの生画像データを使用します。画像デコーダを使用すると、実行時に画像データをデコードしてレンダリングすることができます。詳細については、「Qt Quick Ultralite imagedecoder Example」および「Using JPEG decoder」を参照してください。

注：グラフィックスドライバの制限により 、現在、ソースJPEG画像でサポートされているサブサンプリングモードはYUV420のみです。詳細については、『JPEGデコードドライバ TRAVEO T2G クラスタシリーズユーザーマニュアル』の「サンプルアプリケーションユーザガイド」を参照してください。ソース画像をYUV420サブサンプリング形式に変換するには、ImageMagickのConvertツールを使用できます：convert input.jpg -sampling-factor 4:2:0 output.jpg 。

注： Infineon TRAVEO T2G CYT4DNの場合、必須の CMake 変数TVII_JPEG_DRIVER_DIR を設定してください。この変数は、JPEG デコードドライバ SDK のルートフォルダを指すように設定する必要があります。

RH850プラットフォームでは、JPEGドライバを構成するために以下のコンパイル定義を追加してください：

USE_OUTPUT_SPLIT_MODE
Renesas JCUAハードウェアを、デコードがチャンク単位で行われるディビジョンモードに設定します。画像全体を一度にデコードする通常モードを使用する場合は、この定義を省略できます。
DECODE_BUFFER_PIXEL_LINES
USE_OUTPUT_SPLIT_MODE が有効になっている場合、DECODE_BUFFER_PIXEL_LINES は、1回の反復処理で処理される出力バッファのピクセル行数を設定します。この値は16の倍数でなければなりません。

DECODE_BUFFER_PIXEL_LINES のデフォルト値は16です。
CHROMA_SUBSAMPLING
使用中の画像のクロマサブサンプリング形式を設定します。設定可能な値は以下の通りです:
1. R_JCUA_JPEG_FORMAT_YCBCR420
2. R_JCUA_JPEG_FORMAT_YCBCR411
3. R_JCUA_JPEG_FORMAT_YCBCR422
4. R_JCUA_JPEG_FORMAT_YCBCR444
CHROMA_SUBSAMPLING のデフォルト値は R_JCUA_JPEG_FORMAT_YCBCR420 です。

注：現在 、色差サブサンプリングは実行時に決定することはできず、コンパイル時に指定する必要があります。アプリケーションで使用されるすべてのJPEG画像は、同じ色差サブサンプリングで保存されている必要があります。

その他のボードおよびプラットフォームについては、このプロジェクトではPNG画像ファイルを使用し、Resource Compilerによってビルド時に画像をデコードします。

プロジェクト構造

CMake プロジェクトファイル

以下の CMake の例は、JPEG デコーダを使用しないプラットフォームで画像をデコードする方法を示しています：

qul_add_target(sprite_animations
    QML_PROJECT mcu_sprite_animations.qmlproject
    GENERATE_ENTRYPOINT
)

以下の QmlProject の例は、必要な画像リソースのプロパティとプラットフォーム設定を用いて JPEG デコーダを構成する方法を示しています：

qul_add_target(sprite_animations
    QML_PROJECT mcu_sprite_animations_jpeg.qmlproject
    os/${QUL_OS_LOWERCASE}/main.cpp
)

QmlProjectファイル

QmlProject ファイルには、必要な Qml ファイルと Image ファイルが含まれています。

// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial

import QmlProject 1.3

Project {
    mainFile: "sprite_animations.qml"
    QmlFiles {
        files: [
            "ToggleButton.qml"
        ]
    }
    ImageFiles {
        files: [
            "qt-image-sequence.png"
        ]
        MCU.resourceAnimatedSpriteFrameWidth: 180
        MCU.resourceAnimatedSpriteFrameHeight: 160
    }
}

QmlProject では、ImageFiles.MCU.resourceAnimatedSpriteFrameWidth、ImageFiles.MCU.resourceAnimatedSpriteFrameHeight、およびImageFiles.MCU.resourceAnimatedSpriteOptimizationsを提供しており、これらを使用して画像ソースを最適化できます。

Resource Compilerは、内部で画像ソースを 16 フレームに分割し、クロッピング技術を用いて最適化を行うことで、パフォーマンスの向上とメモリ使用量の削減を実現します。これにより、一連のフレーム間で変更された部分のみをレンダリングできるようになります。

アプリケーション UI

sprite_animations.qml ファイルは、AnimatedSprite 型を定義します。このファイルでは、1フレームのサイズ、画像に含まれるフレーム数、および画像のソースが定義されます。アニメーションはデフォルトで開始されます。ユーザーが画像をクリックすると、現在のrunning の値に基づいて、アニメーションの実行または停止が行われます。

    AnimatedSprite {
        id: sprite
        anchors.centerIn: parent
        source: "qt-image-sequence.png"

        frameDuration: 80
        frameCount: 16
        frameWidth: 180
        frameHeight: 160

        loops: AnimatedSprite.Infinite

        onFinished: {
            txtMsg.text = "Finished"
        }

        onRunningChanged: {
            if (sprite.running) {
                txtMsg.text = ""
            }
        }

        MouseArea {
            anchors.fill: parent
            onClicked: {
                if (sprite.running) {
                    sprite.stop()
                } else {
                    sprite.start()
                }
            }
        }
    }

UIの左上隅には、アニメーションの各フレームの番号と、現在のフレームの再生時間（ミリ秒単位）が表示されます。

    Column {
        id: spriteInfo
        anchors.top: parent.top
        anchors.left: parent.left
        anchors.margins: 16
        spacing: 4

        Text {
            id: txtFrameNo
            text: "frame: " + (sprite.currentFrame + 1) + " / " + sprite.frameCount
            font.pixelSize: 14
            color: "white"
        }
        Text {
            id: txtDuration
            text: "duration: " + sprite.frameDuration
            font.pixelSize: 14
            color: "white"
        }
        Text {
            id: txtMsg
            font.pixelSize: 14
            text: ""
            color: "white"
        }
    }

アプリケーションの右上隅には、loops プロパティの値をAnimatedSprite.Infiniteと1の間で切り替えるボタンがあります。

    ToggleButton {
        id: toggleLoops
        width: parent.width / 4
        height: parent.height / 9
        anchors.right: parent.right
        anchors.top: parent.top
        anchors.margins: 8
        checkedText: "Infinite"
        uncheckedText: "Once"
        onCheckedChanged: {
            if (toggleLoops.checked) {
                sprite.loops = AnimatedSprite.Infinite
            } else {
                sprite.loops = 1
            }
        }
    }

ToggleButtonは、Rectangle 、MouseArea 、Text 、Row などのシンプルなQMLビジュアルタイプを使用したカスタムコンポーネントです。

import QtQuick 2.15

Rectangle {
    id: control
    color: "white"

    property bool checked: true
    readonly property color foregroundColor: "black"
    readonly property int borderWidth: 1
    readonly property alias checkedText: txtChecked.text
    readonly property alias uncheckedText: txtUnchecked.text

    Row {
        x: control.borderWidth
        y: control.borderWidth
        spacing: control.borderWidth

        Rectangle {
            id: leftPart
            width: (control.width - control.borderWidth * 3) / 2
            height: (control.height - control.borderWidth * 2)
            color: control.checked? control.color : control.foregroundColor

            Text {
                id: txtChecked
                anchors.centerIn: parent
                color: control.checked? control.foregroundColor : control.color
                font.pixelSize: 14
            }
        }
        Rectangle {
            id: rightPart
            width: leftPart.width
            height: leftPart.height
            color: control.checked? control.foregroundColor : control.color

            Text {
                id: txtUnchecked
                anchors.centerIn: parent
                color: control.checked? control.color : control.foregroundColor
                font.pixelSize: 14
            }
        }
    }

    MouseArea {
        anchors.fill: parent
        onClicked: control.checked = !control.checked
    }
}

JPEG デコーダの使用

JPEGデコーダを使用するプラットフォームでは、QmlProjectのプロパティであるMCU.resourceKeepRawDataを使用して、JPEGファイルを生の画像データとしてバンドルできます。また、MCU.Config.maxResourceCacheSizeを定義して、実行時にデコードされた画像データを保存するための十分なスペースを確保することもできます。

// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial

import QmlProject 1.3

Project {
    MCU.Config {
        // enough size to contain one decoded image
        maxResourceCacheSize: 153600
    }
    QmlFiles {
        files: [
            "ToggleButton.qml",
            "sprite_animations_jpeg.qml"
        ]
    }
    ImageFiles {
        files: [
            "qt-image-sequence/00.jpg",
            "qt-image-sequence/01.jpg",
            "qt-image-sequence/02.jpg",
            "qt-image-sequence/03.jpg",
            "qt-image-sequence/04.jpg",
            "qt-image-sequence/05.jpg",
            "qt-image-sequence/06.jpg",
            "qt-image-sequence/07.jpg",
            "qt-image-sequence/08.jpg",
            "qt-image-sequence/09.jpg",
            "qt-image-sequence/10.jpg",
            "qt-image-sequence/11.jpg",
            "qt-image-sequence/12.jpg",
            "qt-image-sequence/13.jpg",
            "qt-image-sequence/14.jpg",
            "qt-image-sequence/15.jpg"
        ]
        MCU.resourceAnimatedSprite: true
        MCU.resourceKeepRawData: true
    }
}

この例では、AnimatedSpriteDirectory を使用した一連のフレーム画像を用いて、ハードウェアデコードの利点を強調しています。これにより、スプライトアニメーションのメモリ使用量とCPU負荷が軽減されます。

    AnimatedSpriteDirectory {
        id: sprite
        anchors.centerIn: parent
        sourcePath: "qt-image-sequence"

        frameDuration: 80
        loops: AnimatedSprite.Infinite

        readonly property int frameCount: 16
        ...

ファイル：

画像：

「リソースの管理」も参照してください 。

特定のQtライセンスの下で利用可能です。
詳細はこちら。