QRgb qPremultiply()

2025-05-26

`QRgb qPremultiply(QRgb rgb)` とは

qPremultiply() は、Qtが提供するユーティリティ関数の一つで、アルファ値を乗算済みの色（Premultiplied Alpha Color） に変換するために使用されます。

QRgb: Qtで色を表すために使われる型で、通常は32ビットの符号なし整数（unsigned int）として定義されます。この32ビットの中に、A（アルファ）、R（赤）、G（緑）、B（青）の各成分が格納されています。

アルファ値の乗算（Premultiplied Alpha）とは？

通常のRGBA形式の色データでは、各色成分（赤、緑、青）は0から255までの範囲で表現され、アルファ値（透明度）も同様に0から255で表現されます。ここで、アルファ値が0は完全に透明、255は完全に不透明を意味します。

しかし、グラフィックスのレンダリング、特に合成（Compositing）処理においては、「アルファ値が乗算済み」の形式がよく用いられます。これは、各色成分（R, G, B）にそのピクセルのアルファ値（A）をあらかじめ乗算しておくというものです。

通常のRGBA
R, G, B, A (各成分が独立している)

アルファ乗算済みRGBA
R' = R * (A / 255.0) G' = G * (A / 255.0) B' = B * (A / 255.0) A (アルファ値自体はそのまま保持されることが多い)

例えば、半透明の赤い色（R=255, G=0, B=0, A=128）を考えます。

アルファ乗算済みの場合
- R' = 255 * (128 / 255.0) = 128
- G' = 0 * (128 / 255.0) = 0
- B' = 0 * (128 / 255.0) = 0
- 結果: (128, 0, 0, 128)
通常の場合
(255, 0, 0, 128)

なぜアルファ乗算済みにするのか？

主な理由は、合成処理の効率化と正確性にあります。

合成処理の簡略化
2つの画像を合成する際、通常のRGBA形式だと、各ピクセルの色成分を計算してからアルファ値を適用するという複数のステップが必要です。しかし、アルファ乗算済みであれば、単純な加算で合成が可能です。 C_result = C_source + C_destination * (1 - A_source) (通常の合成式) C'_result = C'_source + C'_destination (アルファ乗算済みの場合) ここで、Cは色、Aはアルファ値、C′はアルファ乗算済みの色です。これにより、計算が高速になります。
アルファ値が0の場合の色の扱い
完全に透明なピクセル（アルファ値が0）の場合、そのピクセルのRGB値は何であっても最終的な描画には影響しません。しかし、通常のRGBA形式だと、RGB値には何らかの値が入っています。アルファ乗算済みであれば、アルファ値が0のピクセルは、R', G', B' も全て0になり、完全に黒（透明な黒）として統一的に扱われるため、データの一貫性が保たれ、意図しない色の漏れなどを防ぐことができます。

`qPremultiply()` 関数の役割

qPremultiply(QRgb rgb) 関数は、入力として与えられたQRgb値（通常のRGBA形式）を、上記で説明したアルファ乗算済み形式のQRgb値に変換して返します。

Qtの多くの描画関数（例えば、QImageのピクセルデータ処理や、OpenGLとの連携など）では、パフォーマンスや正確性のためにアルファ乗算済みの色データが内部的に使用されることがあります。そのため、自分でピクセルデータを操作する際などに、この関数が役立ちます。

#include <QDebug>
#include <QColor> // QColorを使うとより簡単に色を扱えますが、ここではQRgbを直接扱います

// qPremultiply関数はQColorクラスの一部ではないため、グローバル関数として提供されます。
// QColor::fromRgb(), QColor::rgba() などと組み合わせて使うことが多いです。

int main() {
    // 例1: 半透明の赤
    QRgb originalRed = qRgba(255, 0, 0, 128); // 赤:255, 緑:0, 青:0, アルファ:128 (半透明)
    qDebug() << "Original Red (RGBA): " << qRed(originalRed) << qGreen(originalRed) << qBlue(originalRed) << qAlpha(originalRed);

    QRgb premultipliedRed = qPremultiply(originalRed);
    qDebug() << "Premultiplied Red (RGBA): " << qRed(premultipliedRed) << qGreen(premultipliedRed) << qBlue(premultipliedRed) << qAlpha(premultipliedRed);
    // 出力例: Premultiplied Red (RGBA): 128 0 0 128 (約 255 * (128/255) = 128)

    // 例2: 完全に不透明な青
    QRgb originalBlue = qRgba(0, 0, 255, 255); // 青:255, アルファ:255 (不透明)
    qDebug() << "Original Blue (RGBA): " << qRed(originalBlue) << qGreen(originalBlue) << qBlue(originalBlue) << qAlpha(originalBlue);

    QRgb premultipliedBlue = qPremultiply(originalBlue);
    qDebug() << "Premultiplied Blue (RGBA): " << qRed(premultipliedBlue) << qGreen(premultipliedBlue) << qBlue(premultipliedBlue) << qAlpha(premultipliedBlue);
    // 出力例: Premultiplied Blue (RGBA): 0 0 255 255 (アルファが255なので変化なし)

    // 例3: 完全に透明な緑
    QRgb originalGreen = qRgba(0, 255, 0, 0); // 緑:255, アルファ:0 (完全に透明)
    qDebug() << "Original Green (RGBA): " << qRed(originalGreen) << qGreen(originalGreen) << qBlue(originalGreen) << qAlpha(originalGreen);

    QRgb premultipliedGreen = qPremultiply(originalGreen);
    qDebug() << "Premultiplied Green (RGBA): " << qRed(premultipliedGreen) << qGreen(premultipliedGreen) << qBlue(premultipliedGreen) << qAlpha(premultipliedGreen);
    // 出力例: Premultiplied Green (RGBA): 0 0 0 0 (アルファが0なのでR,G,Bも0になる)

    return 0;
}

QtのQRgb qPremultiply()関数自体は非常にシンプルで、内部的に計算ロジックが完結しているため、直接的な使用でエラーが発生することは稀です。しかし、その用途や期待される結果に対する誤解、または関連するグラフィックス処理との組み合わせによって、意図しない挙動や問題が発生することがあります。

以下に、qPremultiply()に関連して起こりうる一般的な問題と、そのトラブルシューティングについて説明します。

色が期待通りに表示されない（色が薄い、暗い、黒っぽい）

原因
最も一般的な問題は、qPremultiply()を適用した後に、さらに別の場所でアルファブレンド処理が二重に行われていることです。qPremultiply()は、アルファ値を色成分に「乗算済み」にするものです。もし、その色データが、Qtの描画システム（例: QPainter）によって再び通常のアルファブレンド（SRC_ALPHAなど）として扱われると、アルファ値が二重に適用され、色が薄くなったり、暗くなったり、透明度が上がりすぎたりします。

例えば、QImage::Format_ARGB32_Premultiplied 形式のQImageにqPremultiply()で変換したピクセルを書き込み、そのQImageをQPainterで描画する場合などです。QImage::Format_ARGB32_Premultiplied はすでにアルファ乗算済みなので、QPainterはそれをそのまま利用しようとしますが、誤って別の形式に変換したり、あるいは明示的にブレンドモードを設定したりすると問題が起こりえます。

トラブルシューティング

qUnpremultiply()で確認する
qPremultiply()で変換した色が期待通りか確認するために、一時的にqUnpremultiply()を使って元の色に戻してみて、その色が正しく表示されるかを確認するのも有効です。
描画コンテキストと画像のフォーマットを確認する
- QImageを使う場合、QImage::Format_ARGB32_Premultiplied 形式で画像を作成しているか確認してください。この形式は、ピクセルデータが既にアルファ乗算済みであることをQtに伝えます。
- QPainterで描画する際、QPainter::CompositionMode （合成モード）が適切に設定されているか確認してください。デフォルトのQPainter::CompositionMode_SourceOver は通常、アルファ乗算済みの色とうまく機能しますが、明示的にQPainter::CompositionMode_Source や他のモードを試す必要があるかもしれません。
- 特に、OpenGLとの連携など、Qtの描画システムの外でピクセルデータを扱う場合は、アルファ乗算済みの概念が正しく伝わっているかを検証する必要があります。OpenGLのglBlendFunc設定が、GL_ONE, GL_ONE_MINUS_SRC_ALPHA （これはアルファ乗算済み用）ではなく、GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA （通常用）になっていると、二重にアルファが適用されてしまいます。

コンパイルエラー

原因

QRgb型への誤解
QRgbは色を表すtypedefであり、クラスや関数ではありません。そのため、QRgb(r,g,b,a)のようなコンストラクタ呼び出しはできません。qRgb()やqRgba()などのヘルパー関数を使ってQRgb値を作成する必要があります。
ヘッダファイルの不足
qPremultiply()はグローバル関数であり、使用するには適切なヘッダファイルをインクルードする必要があります。通常は<QColor>または<QtGui/qcolor.h>に含まれています。

トラブルシューティング

QRgb値の作成にはqRgb()またはqRgba()を使用する。 例: QRgb color = qRgba(255, 0, 0, 128);
#include <QColor> を追加する。

透明度が正しく表現されない（透明な部分が黒くなるなど）

原因

画像形式と描画コンテキストの不一致
QImageの形式がFormat_ARGB32_Premultipliedでないにもかかわらず、qPremultiply()で変換したピクセルを書き込んでいる場合、Qtの描画エンジンがそのデータを正しく解釈できない可能性があります。特に、Format_RGB32などのアルファ値を持たない形式や、Format_ARGB32（アルファ乗算なし）形式でアルファ乗算済みデータを扱うと問題が生じます。
アルファ乗算済みの概念の誤解
完全に透明な色（アルファ値が0）の場合、qPremultiply()を適用すると、R, G, B成分も全て0になります。これは**「透明な黒」**を意味します。もしこの「透明な黒」を不透明なコンテキストに描画しようとすると、黒い部分が残って見えることがあります。

トラブルシューティング

デバッグと検証
- qRed(), qGreen(), qBlue(), qAlpha()を使って、qPremultiply()適用前後の各色成分の値をqDebug()で出力し、期待通りの値になっているか確認してください。
- 簡単なテストケースを作成し、qPremultiply()を適用した色と適用しない色の両方を描画して、視覚的な違いを比較してください。
QImageの形式を正しく設定する
qPremultiply()で変換したピクセルデータを格納するQImageは、可能な限りQImage::Format_ARGB32_Premultiplied形式で初期化してください。
意図しない黒い部分
完全に透明なピクセルは「透明な黒」になることを理解する。もし黒く見えて困る場合は、その部分の描画をスキップするか、背景色で埋めるなどの対処を検討する。

パフォーマンスの問題（稀）

qPremultiply()自体は非常に軽量な関数ですが、ループ内で大量のピクセルに対して繰り返し呼び出す場合は、パフォーマンスに影響を与える可能性があります。

Qtの組み込み機能の利用
QImage::convertToFormat(QImage::Format_ARGB32_Premultiplied) のように、Qtが提供する効率的な形式変換関数を利用することを検討してください。これは、C++でピクセルを1つずつ処理するよりも、内部的に最適化された実装が使われているため、高速である可能性があります。
必要最小限の適用
ピクセルデータを一度だけアルファ乗算済み形式に変換し、それを再利用するようにします。例えば、QImage全体をQImage::Format_ARGB32_Premultiplied形式に変換してから描画するなど。

`QRgb qPremultiply()` を使用したプログラミング例

QImageのピクセルを手動で処理する

この例では、QImageを作成し、そのピクセルデータを手動でqPremultiply()を使って変換し、最終的に画像として保存・表示します。

#include <QApplication>
#include <QImage>
#include <QRgb>
#include <QDebug>
#include <QPainter> // QImageをウィンドウに表示するために使用
#include <QLabel>   // QImageを表示するためのウィジェット

// qPremultiply関数はQColorに含まれています。
#include <QColor>

int main(int argc, char *argv[]) {
    QApplication app(argc, argv);

    const int width = 200;
    const int height = 100;

    // アルファ乗算済み形式のQImageを作成
    // この形式を使うことで、QPainterなどがアルファ乗算済みのデータを期待通りに扱います。
    QImage image(width, height, QImage::Format_ARGB32_Premultiplied);

    // 画像を完全に透明な色で初期化（アルファ乗算済みなのでR,G,Bも0）
    image.fill(qRgba(0, 0, 0, 0));

    // グラデーションを作成し、アルファ乗算を適用
    for (int y = 0; y < height; ++y) {
        QRgb *scanLine = reinterpret_cast<QRgb*>(image.scanLine(y));
        for (int x = 0; x < width; ++x) {
            int alpha = (int)(255.0 * x / width); // 左から右へ透明度が変化 (0から255)
            int red = 255;
            int green = 0;
            int blue = 0;

            // 元のRGBA値を作成
            QRgb originalRgb = qRgba(red, green, blue, alpha);

            // qPremultiply() を使ってアルファ乗算済みの色に変換
            QRgb premultipliedRgb = qPremultiply(originalRgb);

            // 画像のピクセルを設定
            scanLine[x] = premultipliedRgb;
        }
    }

    // 作成した画像をファイルに保存（PNGはアルファチャンネルをサポート）
    image.save("premultiplied_gradient.png");
    qDebug() << "Saved premultiplied_gradient.png";

    // QLabelに画像を表示
    QLabel label;
    label.setWindowTitle("Premultiplied Alpha Example");
    label.setPixmap(QPixmap::fromImage(image));
    label.show();

    return app.exec();
}

解説

この例では、左から右へ赤色の透明度が徐々に変化するグラデーションを作成しています。アルファ乗算されているため、左端（透明度0）は完全に黒（R,G,Bも0）になり、右端（透明度255）は純粋な赤になります。
qRgba()で通常のRGBA色を作成し、それをqPremultiply()でアルファ乗算済み形式に変換しています。
QImage::Format_ARGB32_Premultiplied を使用することで、QImageがこの形式の色データを正しく処理することをQtに伝えています。

QPainterと組み合わせて合成を行う

この例では、qPremultiply()で手動で処理した色と、Qtの描画システムが自動的にアルファ乗算を考慮するQPainterの振る舞いを比較します。

#include <QApplication>
#include <QWidget>
#include <QPainter>
#include <QImage>
#include <QColor> // qPremultiply, qRgba, qRed, qGreen, qBlue, qAlpha

// カスタムウィジェット
class PremultiplyExampleWidget : public QWidget {
public:
    PremultiplyExampleWidget(QWidget *parent = nullptr) : QWidget(parent) {
        setWindowTitle("Premultiply QPainter Example");
        resize(400, 200);
    }

protected:
    void paintEvent(QPaintEvent *event) override {
        QPainter painter(this);
        painter.setRenderHint(QPainter::Antialiasing);

        // 背景に格子模様を描画して、透明度を分かりやすくする
        painter.setBrush(Qt::lightGray);
        for (int i = 0; i < width(); i += 20) {
            for (int j = 0; j < height(); j += 20) {
                if ((i / 20 + j / 20) % 2 == 0) {
                    painter.drawRect(i, j, 20, 20);
                }
            }
        }

        // --- 左側: qPremultiply() を使ってピクセルを直接設定した画像 ---
        QImage premultImage(width() / 2 - 20, height() - 40, QImage::Format_ARGB32_Premultiplied);
        premultImage.fill(qRgba(0, 0, 0, 0)); // 透明な黒で初期化

        // 半透明な青色グラデーション
        for (int y = 0; y < premultImage.height(); ++y) {
            QRgb *scanLine = reinterpret_cast<QRgb*>(premultImage.scanLine(y));
            int alpha = (int)(255.0 * y / premultImage.height()); // 上から下へ透明度が変化
            QRgb originalBlue = qRgba(0, 0, 255, alpha); // 元の青色 (アルファ乗算前)
            scanLine[0] = qPremultiply(originalBlue); // 例として1ピクセルだけ色を設定
            for (int x = 0; x < premultImage.width(); ++x) {
                 QRgb originalBlue = qRgba(0, 0, 255, alpha);
                 scanLine[x] = qPremultiply(originalBlue);
            }
        }
        painter.drawImage(10, 20, premultImage);
        painter.drawText(10, 15, "Premultiplied Image");


        // --- 右側: QPainter が自動的にアルファブレンドする描画 ---
        // QColorで半透明な赤を作成
        QColor semiTransparentRed(255, 0, 0, 128); // 赤、アルファ128 (半透明)
        painter.setBrush(semiTransparentRed);
        painter.setPen(Qt::NoPen);

        // 四角形を描画
        painter.drawRect(width() / 2 + 10, 20, width() / 2 - 20, height() - 40);
        painter.drawText(width() / 2 + 10, 15, "QPainter Alpha Blending");

        // もう一つ、不透明な青を上に重ねてみる
        QColor opaqueBlue(0, 0, 255, 255);
        painter.setBrush(opaqueBlue);
        painter.drawRect(width() / 2 + 30, 40, 50, 50); // 一部を重ねる
    }
};

int main(int argc, char *argv[]) {
    QApplication app(argc, argv);

    PremultiplyExampleWidget widget;
    widget.show();

    return app.exec();
}

解説

右側では、QColorで直接アルファ値を持つ色を作成し、QPainter::drawRect()で描画しています。QtのQPainterは、標準のQColorを使って描画する場合、自動的にアルファブレンド処理（アルファ乗算と合成）を行います。 したがって、通常は手動でqPremultiply()を呼び出す必要はありません。
左側では、QImage::Format_ARGB32_Premultiplied 形式のQImageにqPremultiply()を使ってピクセルを書き込んでいます。QPainter::drawImage() はこの形式を認識し、適切な方法で合成します。

qUnpremultiply() との組み合わせ

qPremultiply()でアルファ乗算した色を、元の（アルファ乗算されていない）形式に戻すqUnpremultiply()関数と合わせて使う例です。デバッグや、特定の外部APIに渡すために元の形式に戻す必要がある場合などに役立ちます。

#include <QCoreApplication>
#include <QDebug>
#include <QColor> // qPremultiply, qUnpremultiply, qRgba, qRed, qGreen, qBlue, qAlpha

int main(int argc, char *argv[]) {
    QCoreApplication app(argc, argv);

    // 元の半透明な色 (赤)
    QRgb originalColor = qRgba(255, 0, 0, 128); // 赤:255, 緑:0, 青:0, アルファ:128

    qDebug() << "--- Original Color ---";
    qDebug() << "Red:" << qRed(originalColor)
             << "Green:" << qGreen(originalColor)
             << "Blue:" << qBlue(originalColor)
             << "Alpha:" << qAlpha(originalColor);

    // qPremultiply() でアルファ乗算
    QRgb premultipliedColor = qPremultiply(originalColor);

    qDebug() << "\n--- Premultiplied Color ---";
    qDebug() << "Red:" << qRed(premultipliedColor)
             << "Green:" << qGreen(premultipliedColor)
             << "Blue:" << qBlue(premultipliedColor)
             << "Alpha:" << qAlpha(premultipliedColor);

    // qUnpremultiply() で元の形式に戻す
    QRgb unpremultipliedColor = qUnpremultiply(premultipliedColor);

    qDebug() << "\n--- Unpremultiplied Color (after premultiply and unpremultiply) ---";
    qDebug() << "Red:" << qRed(unpremultipliedColor)
             << "Green:" << qGreen(unpremultipliedColor)
             << "Blue:" << qBlue(unpremultipliedColor)
             << "Alpha:" << qAlpha(unpremultipliedColor);

    // 完全に透明な色の場合
    QRgb transparentColor = qRgba(100, 200, 50, 0); // 緑っぽい色だが、アルファは0 (完全に透明)
    qDebug() << "\n--- Transparent Color ---";
    qDebug() << "Original (RGBA):" << qRed(transparentColor) << qGreen(transparentColor) << qBlue(transparentColor) << qAlpha(transparentColor);

    QRgb premultTransparent = qPremultiply(transparentColor);
    qDebug() << "Premultiplied (RGBA):" << qRed(premultTransparent) << qGreen(premultTransparent) << qBlue(premultTransparent) << qAlpha(premultTransparent);
    // 出力: Premultiplied (RGBA): 0 0 0 0 (アルファ0なのでR,G,Bも0になる)

    QRgb unpremultTransparent = qUnpremultiply(premultTransparent);
    qDebug() << "Unpremultiplied (RGBA):" << qRed(unpremultTransparent) << qGreen(unpremultTransparent) << qBlue(unpremultTransparent) << qAlpha(unpremultTransparent);
    // 出力: Unpremultiplied (RGBA): 0 0 0 0 (元のR,G,Bは失われるため、元の色が復元できない)
    // これは重要なポイント: アルファが0の場合、R,G,Bの情報は失われ、元の色には戻せない。

    return app.exec();
}

解説

qUnpremultiply()は、qPremultiply()の逆の操作を行います。しかし、アルファ値が0の場合、元のR, G, B成分の情報は完全に失われるため、qUnpremultiply()を適用しても元の色には戻りません。これは、アルファ乗算済み形式の性質上避けられない挙動です。
qPremultiply()は色成分にアルファ値を乗算します。例えば、qRed(originalColor)が255、qAlpha(originalColor)が128の場合、qRed(premultipliedColor)は約128（255 * (128 / 255)）になります。

これらの例から、qPremultiply()がどのように色データを変換し、Qtのグラフィックスシステムとどのように連携するかを理解できるかと思います。通常、QPainterで描画を行う際はQtが自動的に処理を行うため、qPremultiply()を直接呼び出すことは稀ですが、低レベルでピクセルデータを操作する場合や、特定の画像形式（例えば、OpenGLのテクスチャなど）と連携する場合に非常に役立ちます。 Qt の QRgb qPremultiply() 関数は、主にアルファブレンドを伴う画像処理や描画の際に使用されます。ここでは、具体的なコード例をいくつか示し、その使い方と、関連する概念（QImage::Format_ARGB32_Premultiplied や QPainter の合成モード）との組み合わせについて解説します。

qPremultiply() の基本的な使い方

この例では、半透明の赤い色をqPremultiply()で変換し、その前後で各色成分がどのように変化するかを確認します。

#include <QCoreApplication>
#include <QDebug>
#include <QColor> // qPremultiply, qRgba, qRed, qGreen, qBlue, qAlpha を含む

int main(int argc, char *argv[])
{
    QCoreApplication a(argc, argv);

    // 元のRGBA色データ (R=255, G=0, B=0, A=128 - 半透明の赤)
    // QRgb は通常、0xAARRGGBB の形式で格納される unsigned int です。
    QRgb originalColor = qRgba(255, 0, 0, 128); // 赤、半透明

    qDebug() << "--- Original Color ---";
    qDebug() << "Red:   " << qRed(originalColor);
    qDebug() << "Green: " << qGreen(originalColor);
    qDebug() << "Blue:  " << qBlue(originalColor);
    qDebug() << "Alpha: " << qAlpha(originalColor);
    qDebug() << QString("Hex:   %1").arg(originalColor, 8, 16, QChar('0')).toUpper();

    // qPremultiply() を適用
    QRgb premultipliedColor = qPremultiply(originalColor);

    qDebug() << "\n--- Premultiplied Color ---";
    qDebug() << "Red:   " << qRed(premultipliedColor); // 255 * (128/255) = 128
    qDebug() << "Green: " << qGreen(premultipliedColor); // 0 * (128/255) = 0
    qDebug() << "Blue:  " << qBlue(premultipliedColor); // 0 * (128/255) = 0
    qDebug() << "Alpha: " << qAlpha(premultipliedColor); // アルファはそのまま
    qDebug() << QString("Hex:   %1").arg(premultipliedColor, 8, 16, QChar('0')).toUpper();

    // 完全に不透明な色の場合 (アルファが255)
    QRgb opaqueColor = qRgba(0, 0, 255, 255); // 不透明な青
    QRgb premultipliedOpaque = qPremultiply(opaqueColor);
    qDebug() << "\n--- Opaque Color (Premultiplied) ---";
    qDebug() << "Red:   " << qRed(premultipliedOpaque);   // 変化なし: 0
    qDebug() << "Green: " << qGreen(premultipliedOpaque); // 変化なし: 0
    qDebug() << "Blue:  " << qBlue(premultipliedOpaque);  // 変化なし: 255
    qDebug() << "Alpha: " << qAlpha(premultipliedOpaque); // 変化なし: 255

    // 完全に透明な色の場合 (アルファが0)
    QRgb transparentColor = qRgba(0, 255, 0, 0); // 透明な緑
    QRgb premultipliedTransparent = qPremultiply(transparentColor);
    qDebug() << "\n--- Transparent Color (Premultiplied) ---";
    qDebug() << "Red:   " << qRed(premultipliedTransparent);   // 0 * (0/255) = 0
    qDebug() << "Green: " << qGreen(premultipliedTransparent); // 255 * (0/255) = 0
    qDebug() << "Blue:  " << qBlue(premultipliedTransparent);  // 0 * (0/255) = 0
    qDebug() << "Alpha: " << qAlpha(premultipliedTransparent); // 変化なし: 0 (透明な黒になる)

    return 0; // QCoreApplication::exec() は不要 (コンソールアプリのため)
}

実行結果の例

--- Original Color ---
Red:    255
Green:  0
Blue:   0
Alpha:  128
Hex:    80FF0000

--- Premultiplied Color ---
Red:    128
Green:  0
Blue:   0
Alpha:  128
Hex:    80800000

--- Opaque Color (Premultiplied) ---
Red:    0
Green:  0
Blue:   255
Alpha:  255

--- Transparent Color (Premultiplied) ---
Red:    0
Green:  0
Blue:   0
Alpha:  0

QImage::Format_ARGB32_Premultiplied と QPainter を使用した描画

この例では、qPremultiply()で変換したピクセルデータをQImageに直接書き込み、それをQPainterで描画する方法を示します。QImageのフォーマットをQImage::Format_ARGB32_Premultipliedに設定することが重要です。

#include <QApplication>
#include <QLabel>
#include <QPixmap>
#include <QImage>
#include <QPainter>
#include <QRgb> // qPremultiply, qRgba を含む

class ImageDisplayWidget : public QLabel
{
public:
    ImageDisplayWidget(QWidget *parent = nullptr) : QLabel(parent)
    {
        setFixedSize(300, 300);

        // 描画ターゲットとなるQImageを作成
        // フォーマットを QImage::Format_ARGB32_Premultiplied に設定することが重要
        QImage image(size(), QImage::Format_ARGB32_Premultiplied);
        image.fill(Qt::transparent); // 初期化として透明で埋める

        // 半透明の赤い色を準備
        QRgb originalRed = qRgba(255, 0, 0, 128); // 半透明の赤
        QRgb premultipliedRed = qPremultiply(originalRed);

        // 画像の中心に四角を描画
        int rectSize = 100;
        int x = (width() - rectSize) / 2;
        int y = (height() - rectSize) / 2;

        // QPainter を使って描画
        QPainter painter(&image);
        // 通常はQPainter::CompositionMode_SourceOver (デフォルト) を使用
        // アルファ乗算済み画像の場合、SourceOver は期待通りに動作します。
        painter.setCompositionMode(QPainter::CompositionMode_SourceOver);

        // QColor を使用して色を設定することもできます。
        // QColor は内部で自動的にアルファ乗算を処理します。
        // ここではQRgbを直接扱うため、QColor::fromRgba(premultipliedRed) とはせず
        // QColor(premultipliedRed) のように直接QRgbを渡すことで、
        // QColorがその値をアルファ乗算済みとして解釈するようにします。
        // ただし、より直接的な方法として、QRgbをそのまま利用することも可能です。
        painter.setBrush(QBrush(QColor(premultipliedRed))); // プレ乗算済みの色を使用
        painter.setPen(Qt::NoPen);
        painter.drawRect(x, y, rectSize, rectSize);

        // 中央にテキストを描画
        painter.setPen(Qt::white);
        painter.setFont(QFont("Arial", 20));
        painter.drawText(image.rect(), Qt::AlignCenter, "Premultiplied Alpha");

        painter.end(); // QPainter の使用を終了

        // QImage を QLabel に表示するために QPixmap に変換
        setPixmap(QPixmap::fromImage(image));
    }
};

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    ImageDisplayWidget widget;
    widget.setWindowTitle("Premultiplied Alpha Example");
    widget.show();

    return app.exec();
}

この例では、QPainter がアルファ乗算済みの色データを正しく解釈し、背景と適切に合成されます。

ピクセルデータへの直接書き込みとqPremultiply()

この例では、QImageのピクセルデータに直接アクセスし、qPremultiply()を使って色を書き込む方法を示します。

#include <QApplication>
#include <QLabel>
#include <QPixmap>
#include <QImage>
#include <QRgb> // qPremultiply, qRgba を含む

class DirectPixelManipWidget : public QLabel
{
public:
    DirectPixelManipWidget(QWidget *parent = nullptr) : QLabel(parent)
    {
        setFixedSize(300, 300);

        // 描画ターゲットとなるQImageを作成
        // ピクセルを直接操作する場合は、QImage::Format_ARGB32_Premultiplied 形式が推奨される。
        // そうしないと、描画時に期待通りのブレンド結果にならない可能性がある。
        QImage image(size(), QImage::Format_ARGB32_Premultiplied);
        image.fill(Qt::transparent); // 初期化として透明で埋める

        // 複数の色の半透明の点を描画
        // ランダムな位置と色でピクセルを打つ
        for (int i = 0; i < 5000; ++i) {
            int x = QRandomGenerator::global()->bounded(width());
            int y = QRandomGenerator::global()->bounded(height());

            // ランダムな色とアルファ値 (50% 透明)
            QRgb originalColor = qRgba(QRandomGenerator::global()->bounded(256),
                                       QRandomGenerator::global()->bounded(256),
                                       QRandomGenerator::global()->bounded(256),
                                       128); // 半透明

            // アルファ乗算済みの色に変換
            QRgb premultipliedColor = qPremultiply(originalColor);

            // ピクセルを直接設定 (QImage::setPixel は Format_ARGB32_Premultiplied をサポート)
            image.setPixel(x, y, premultipliedColor);
        }

        // QImage を QLabel に表示するために QPixmap に変換
        setPixmap(QPixmap::fromImage(image));
    }
};

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    DirectPixelManipWidget widget;
    widget.setWindowTitle("Direct Pixel Manipulation (Premultiplied)");
    widget.show();

    return app.exec();
}

この例では、QImage::setPixel() を使って個々のピクセルにアルファ乗算済みの色を設定しています。QImageのフォーマットがFormat_ARGB32_Premultipliedであるため、Qtの内部描画処理がこのデータを正しく扱い、他のレイヤーとの合成時に適切な結果が得られます。

QPainter::CompositionMode_Sourceは、描画元（Source）のピクセルを、描画先（Destination）のピクセルに上書きするモードです。このモードは、アルファ乗算済みの色を「素のまま」描画したい場合に便利です。例えば、既にアルファ乗算済みの画像を、その透明度を維持したまま別の画像に貼り付けたい場合などです。

#include <QApplication>
#include <QLabel>
#include <QPixmap>
#include <QImage>
#include <QPainter>
#include <QRgb>

class SourceCompositionWidget : public QLabel
{
public:
    SourceCompositionWidget(QWidget *parent = nullptr) : QLabel(parent)
    {
        setFixedSize(400, 200);

        // 背景画像 (青い四角)
        QImage backgroundImage(size(), QImage::Format_ARGB32);
        backgroundImage.fill(Qt::blue);

        // 半透明の赤い画像 (Sourceとなる画像)
        // ここでは便宜上、QImage::Format_ARGB32 を使用し、
        // 描画時に qPremultiply() で色を変換します。
        // または、直接 Format_ARGB32_Premultiplied で作成しても良いです。
        QImage sourceImage(150, 150, QImage::Format_ARGB32);
        sourceImage.fill(Qt::transparent); // 透明で初期化

        QPainter sourcePainter(&sourceImage);
        sourcePainter.setPen(Qt::NoPen);
        // 通常のRGBA色 (まだプレ乗算されていない)
        QRgb semiTransparentRed = qRgba(255, 0, 0, 128); // 半透明の赤
        sourcePainter.setBrush(QColor(semiTransparentRed)); // QColorは自動的にRGBAを扱う
        sourcePainter.drawEllipse(sourceImage.rect()); // 円を描画
        sourcePainter.end();

        // 最終的な描画を行う QImage
        QImage resultImage(size(), QImage::Format_ARGB32_Premultiplied);
        resultImage.fill(Qt::transparent); // 透明で初期化

        QPainter resultPainter(&resultImage);

        // まず背景を描画
        resultPainter.drawImage(0, 0, backgroundImage);

        // 次に、半透明の赤い画像を上に重ねる
        // ここで QPainter::CompositionMode_Source を使用し、
        // SourceImage をアルファ乗算済みのピクセルとして描画したい場合、
        // SourceImage 自体が Format_ARGB32_Premultiplied であるか、
        // drawImage の前にピクセルデータを手動で変換する必要があります。
        // あるいは、QPainter が自動的に処理してくれることを期待する場合、
        // CompositionMode_SourceOver を使用するのが一般的です。

        // より直接的な qPremultiply() の使用例として、
        // sourceImage のピクセルを一つずつ読み込んで premultiply して描画する方法は
        // 非常に非効率的ですが、理解のための一例として示します。
        // 実際には QImage::convertToFormat() が推奨されます。
        // resultPainter.setCompositionMode(QPainter::CompositionMode_Source); // 通常は使わない

        // 一般的なアルファブレンドは SourceOver を使用
        resultPainter.setCompositionMode(QPainter::CompositionMode_SourceOver);

        // qPremultiply() が最も意味を持つのは、QImage::Format_ARGB32_Premultiplied の画像に
        // ピクセルを直接書き込む場合や、OpenGL のテクスチャデータとして渡す場合などです。
        // QPainter::drawImage() は、描画元の画像のフォーマットに基づいて自動的にブレンド処理を行います。
        // なので、QPainter::drawImage() に渡す QImage が Format_ARGB32_Premultiplied であれば、
        // qPremultiply() を手動で呼び出す必要はほとんどありません。
        // しかし、ここでは SourceImage のピクセルを読み取り、qPremultiply() を介して描画する
        // 非効率的ですが理解のためのコードを示します。
        for (int y = 0; y < sourceImage.height(); ++y) {
            for (int x = 0; x < sourceImage.width(); ++x) {
                QRgb originalPixel = sourceImage.pixel(x, y);
                if (qAlpha(originalPixel) > 0) { // 透明でないピクセルのみ処理
                    QRgb premultipliedPixel = qPremultiply(originalPixel);
                    // resultPainter.setPixel(x, y, premultipliedPixel); // QPainterで個別のピクセル設定は非効率
                    // 代わりに、QImage::setPixel を使用
                    resultImage.setPixel(resultPainter.transform().map(QPoint(x + 50, y + 25)), premultipliedPixel); // オフセットして描画
                }
            }
        }

        // QPainter で直接 Image を描画する場合、Qt は自動的に処理を行います。
        // 例えば、sourceImage を Format_ARGB32_Premultiplied に変換してから描画する場合:
        // QImage premultipliedSourceImage = sourceImage.convertToFormat(QImage::Format_ARGB32_Premultiplied);
        // resultPainter.drawImage(50, 25, premultipliedSourceImage);

        resultPainter.end();

        setPixmap(QPixmap::fromImage(resultImage));
    }
};

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    SourceCompositionWidget widget;
    widget.setWindowTitle("QPainter Composition Mode Example");
    widget.show();

    return app.exec();
}

この例は少し複雑になります。qPremultiply()が最も効果を発揮するのは、QImage::Format_ARGB32_Premultiplied形式のピクセルデータを手動で構築する場合や、外部ライブラリから取得したデータをQtの描画システムに適合させる場合などです。QPainter::drawImage()のような高レベルの関数を使用する場合、Qtは通常、内部的に必要な変換を処理します。

qPremultiply()を直接使用する必要があるのは、主に低レベルなピクセル操作を行う場合や、外部の画像データ（OpenGLテクスチャなど）をQtの描画パイプラインに適合させる場合です。それ以外の多くの場合、Qtの組み込み機能や高レベルなAPIを使用する方が、より効率的で安全、かつ簡潔に同じ目標を達成できます。

以下に、qPremultiply()の代替となる主な方法と、それぞれの適用シナリオを説明します。

QImage::Format_ARGB32_Premultiplied を直接使用する

説明
QImageをQImage::Format_ARGB32_Premultipliedフォーマットで作成または変換すると、その画像内のピクセルデータはQtによって自動的にアルファ乗算済みとして扱われます。これにより、QPainterを使用してこの画像を別の画像やウィジェットに描画する際に、正しいアルファブレンドが行われます。

利点

一貫性
Qtの描画パイプライン全体でアルファ乗算済みの概念が一貫して適用されます。
効率的
Qtの内部実装は最適化されており、手動でのピクセルループよりも高速なことが多いです。
自動処理
個々のピクセルを手動で変換する必要がありません。

適用シナリオ

QPainterを使って画像を他の要素とブレンドする一般的な描画タスク。
外部から読み込んだ画像（PNGなど）を、Qtの描画システムで最適なパフォーマンスで合成したい場合。
新しい透明な画像を作成し、その上に描画する場合。

コード例

#include <QApplication>
#include <QLabel>
#include <QPixmap>
#include <QImage>
#include <QPainter>
#include <QColor> // QColor を含む

class AutoPremultiplyExample : public QLabel
{
public:
    AutoPremultiplyExample(QWidget *parent = nullptr) : QLabel(parent)
    {
        setFixedSize(300, 300);

        // 背景となるQImageを作成 (例: 緑色)
        QImage backgroundImage(size(), QImage::Format_ARGB32);
        backgroundImage.fill(Qt::green);

        // QPainter を使用して背景に描画
        QPainter bgPainter(&backgroundImage);
        bgPainter.setPen(Qt::white);
        bgPainter.setFont(QFont("Arial", 16));
        bgPainter.drawText(rect(), Qt::AlignCenter, "Background (Green)");
        bgPainter.end();


        // アルファ乗算済みフォーマットでQImageを作成
        // この画像に描画される色は、自動的にアルファ乗算されます。
        QImage overlayImage(size(), QImage::Format_ARGB32_Premultiplied);
        overlayImage.fill(Qt::transparent); // 透明で初期化

        // overlayImage に QPainter で描画
        QPainter overlayPainter(&overlayImage);
        overlayPainter.setPen(Qt::NoPen);

        // 半透明の赤を設定
        // QColor を設定すると、QPainter は描画先の画像フォーマットに応じて
        // 適切にアルファ乗算を処理します。
        QColor semiTransparentRed(255, 0, 0, 128); // QColorは非乗算アルファで初期化
        overlayPainter.setBrush(semiTransparentRed);
        overlayPainter.drawEllipse(50, 50, 200, 200); // 円を描画
        overlayPainter.end();

        // 最終的な画像を作成し、背景とオーバーレイを合成
        QImage finalImage(size(), QImage::Format_ARGB32);
        QPainter finalPainter(&finalImage);
        finalPainter.drawImage(0, 0, backgroundImage); // 背景を描画
        finalPainter.drawImage(0, 0, overlayImage);   // オーバーレイ画像を描画
        finalPainter.end();

        setPixmap(QPixmap::fromImage(finalImage));
    }
};

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    AutoPremultiplyExample widget;
    widget.setWindowTitle("QImage::Format_ARGB32_Premultiplied Example");
    widget.show();

    return app.exec();
}

この例では、overlayImageがFormat_ARGB32_Premultipliedで作成されているため、overlayPainterがsemiTransparentRedで円を描画する際、その色データは自動的にアルファ乗算済みになります。そして、finalPainterがoverlayImageを描画する際も、既にアルファ乗算済みであるため、期待通りの合成結果が得られます。

QImage::convertToFormat() を使用する

説明
既存のQImageがFormat_ARGB32（非乗算アルファ）などの形式で、それをアルファ乗算済み形式に変換したい場合に便利です。

利点

簡潔性
変換のためのコードが非常にシンプルです。
既存画像への適用
読み込んだ画像や既存のピクセルデータを簡単に変換できます。

適用シナリオ

別のライブラリから取得した画像データをQtの描画システムに統合する場合。
ファイルから画像をロードし、その画像をQPainterで重ね合わせる前にアルファ乗算済みにしておきたい場合。

コード例

#include <QApplication>
#include <QLabel>
#include <QPixmap>
#include <QImage>
#include <QPainter>
#include <QColor>

class ConvertToPremultipliedExample : public QLabel
{
public:
    ConvertToPremultipliedExample(QWidget *parent = nullptr) : QLabel(parent)
    {
        setFixedSize(300, 300);

        // 背景となるQImage (例: オレンジ色)
        QImage backgroundImage(size(), QImage::Format_ARGB32);
        backgroundImage.fill(QColor(255, 165, 0)); // オレンジ

        // 読み込むことを想定した元の画像 (例: 半透明の円を直接描画)
        // QImage::Format_ARGB32 は非乗算アルファ
        QImage originalSourceImage(size(), QImage::Format_ARGB32);
        originalSourceImage.fill(Qt::transparent); // 透明で初期化

        QPainter sourcePainter(&originalSourceImage);
        sourcePainter.setPen(Qt::NoPen);
        sourcePainter.setBrush(QColor(0, 0, 255, 128)); // 半透明の青
        sourcePainter.drawEllipse(75, 75, 150, 150); // 円を描画
        sourcePainter.end();


        // originalSourceImage をアルファ乗算済みフォーマットに変換
        QImage premultipliedSourceImage = originalSourceImage.convertToFormat(QImage::Format_ARGB32_Premultiplied);

        // 最終的な画像を作成し、背景と変換した画像を合成
        QImage finalImage(size(), QImage::Format_ARGB32);
        QPainter finalPainter(&finalImage);
        finalPainter.drawImage(0, 0, backgroundImage);       // 背景を描画

        // 変換済みの画像を合成
        // QPainter::drawImage は、描画元の画像のフォーマットに基づいて自動的に正しいブレンドを行います。
        finalPainter.drawImage(0, 0, premultipliedSourceImage);
        finalPainter.end();

        setPixmap(QPixmap::fromImage(finalImage));
    }
};

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    ConvertToPremultipliedExample widget;
    widget.setWindowTitle("QImage::convertToFormat Example");
    widget.show();

    return app.exec();
}

この場合も、qPremultiply()を個々のピクセルに手動で適用することなく、高レベルな関数呼び出しで目的を達成しています。

QPainter::CompositionMode の適切な設定

説明
QPainterは様々な合成モードを提供しており、これらを設定することで描画元の色と描画先の色のブレンド方法を制御できます。アルファ乗算済みの色データを使用する場合、QPainter::CompositionMode_SourceOver（デフォルト）が通常適切です。しかし、他のモードを試すことで異なる視覚効果を得ることもできます。

利点

高レベル制御
低レベルなピクセル操作なしに描画結果を調整できます。
柔軟な合成
描画の際に多様なブレンド効果を実現できます。

適用シナリオ

描画のパフォーマンスと視覚的品質のバランスを取りたい場合。
複数のレイヤーや画像を特定のルールで合成したい場合。

注意点

QPainter::CompositionMode_Sourceのように単純な上書きモードを使用する場合、描画元のアルファ値が0の場合に、そのピクセルの色情報（R,G,B）がゼロ（透明な黒）になっていることが重要です。qPremultiply()はこの「透明な黒」を保証します。

QColor を使用して色を設定する

説明
QPainter::setBrush() や QPainter::setPen() に QColor オブジェクトを渡す場合、QColorは通常、非乗算アルファのRGBA値として初期化されます（例: QColor(255, 0, 0, 128)）。QPainterは、描画先のQImageやQPixmapのフォーマットに応じて、内部で必要なアルファ乗算処理を自動的に行います。

利点

内部最適化
Qtが適切なタイミングで必要な変換を処理します。
簡潔なAPI
色の扱いや描画が非常に直感的です。

適用シナリオ

カスタムウィジェットで背景や要素を描画する場合。
単一の色で図形やテキストを描画する場合。

QRgb qPremultiply() は特定の目的（手動のピクセル操作など）に特化した低レベルな関数です。Qtのほとんどの描画タスクにおいては、以下に示す高レベルな代替手段を利用する方が一般的であり、推奨されます。

QImage::Format_ARGB32_Premultiplied フォーマットを使用する
QImage::convertToFormat(QImage::Format_ARGB32_Premultiplied) で変換する
QPainter::CompositionMode を適切に設定する
QColor オブジェクトを直接使用して描画する

QRgb qPremultiply()

QRgb qPremultiply(QRgb rgb) とは

アルファ値の乗算（Premultiplied Alpha）とは？

なぜアルファ乗算済みにするのか？

qPremultiply() 関数の役割

色が期待通りに表示されない（色が薄い、暗い、黒っぽい）

コンパイルエラー

透明度が正しく表現されない（透明な部分が黒くなるなど）

パフォーマンスの問題（稀）

QRgb qPremultiply() を使用したプログラミング例

QImageのピクセルを手動で処理する

QPainterと組み合わせて合成を行う

qUnpremultiply() との組み合わせ

qPremultiply() の基本的な使い方

QImage::Format_ARGB32_Premultiplied と QPainter を使用した描画

ピクセルデータへの直接書き込みとqPremultiply()

QImage::Format_ARGB32_Premultiplied を直接使用する

QImage::convertToFormat() を使用する

QPainter::CompositionMode の適切な設定

QColor を使用して色を設定する

`QRgb qPremultiply(QRgb rgb)` とは

`qPremultiply()` 関数の役割

`QRgb qPremultiply()` を使用したプログラミング例