QPixmap Class

メンバ関数のドキュメント

QPixmap::QPixmap()

ヌルピクマップを作成します。

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

[explicit] QPixmap::QPixmap(const char *const[] xpm)

指定されたxpm データからピクマップを構築します。このデータは、有効なXPM画像である必要があります。

エラーは黙って無視されます。

なお、少し変わった宣言を使用することで、XPM変数のサイズをわずかに縮小することが可能です。

static const char * const start_xpm[] = {
    "16 15 8 1",
    "a c #cec6bd",
    // etc.
};

余分なconst により、定義全体が読み取り専用になります。これにより、（たとえば、コードが共有ライブラリ内にある場合など）効率がわずかに向上し、アプリケーションをROMに格納する場合にもROM化が可能になります。

QPixmap::QPixmap(int width, int height)

指定されたwidth およびheight を使用して、ピクマップを構築します。width またはheight のいずれかが0の場合、ヌルピクマップが構築されます。

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

QPixmap::QPixmap(const QString &fileName, const char *format = nullptr, Qt::ImageConversionFlags flags = Qt::AutoColor)

指定されたfileName を持つファイルからピクマップを作成します。ファイルが存在しない場合や形式が不明な場合、ピクマップはnullピクマップとなります。

ローダーは、指定されたformat を使用してピクマップの読み込みを試みます。format が指定されていない場合（これがデフォルトです）、ローダーはファイル内のヘッダーを調査してファイル形式を推測します。

ファイル名は、ディスク上の実際のファイル、またはアプリケーションの組み込みリソースのいずれかを指すことができます。アプリケーションの実行ファイルに画像やその他のリソースファイルを組み込む方法の詳細については、「リソースシステムの概要」を参照してください。

低解像度の出力に合わせて画像を変更する必要がある場合（例：32ビットから8ビットへの変換）、flags を使用して変換を制御します。

fileName 、format 、およびflags の各パラメータは、load() 関数に渡されます。つまり、fileName 内のデータはバイナリにコンパイルされません。fileName に相対パス（例：ファイル名のみ）が含まれている場合、該当するファイルはランタイムの作業ディレクトリを基準として検索される必要があります。

Reading and Writing Image Filesも参照してください 。

[explicit] QPixmap::QPixmap(const QSize &size)

指定されたsize のピクマップを作成します。

QPixmap::QPixmap(const QPixmap &pixmap)

指定されたpixmap のコピーであるピクマップを作成します。

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

[noexcept] QPixmap::QPixmap(QPixmap &&other)

other から QPixmap インスタンスをムーブコンストラクタで生成します。

swap() およびoperator=(QPixmap&&)も参照してください 。

[virtual noexcept] QPixmap::~QPixmap()

ピクマップを破棄します。

qint64 QPixmap::cacheKey() const

このQPixmap を識別する数値を返します。異なるQPixmap オブジェクトが同じキャッシュキーを持つのは、それらが同じコンテンツを参照している場合に限られます。

pixmapが変更されると、cacheKey()の値も変化します。

bool QPixmap::convertFromImage(const QImage &image, Qt::ImageConversionFlags flags = Qt::AutoColor)

指定されたflags を使用して変換を制御し、このピクマップのデータを指定されたimage に置き換えます。flags 引数は、Qt::ImageConversionFlags のビット単位のOR演算の結果です。flags に0を指定すると、すべてのデフォルトオプションが設定されます。結果としてこのピクマップがnullでなくなった場合、true を返します。

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

QPixmap QPixmap::copy(const QRect &rectangle = QRect()) const

指定されたrectangle によって指定されたピクマップのサブセットのディープコピーを返します。ディープコピーの詳細については、「暗黙的なデータ共有」のドキュメントを参照してください。

指定されたrectangle が空の場合、画像全体がコピーされます。

operator=()、QPixmap()、およびPixmap Transformationsも参照してください 。

QPixmap QPixmap::copy(int x, int y, int width, int height) const

矩形QRect （x 、y 、width 、height ）で指定されたピクマップのサブセットのディープコピーを返します。

QBitmap QPixmap::createHeuristicMask(bool clipTight = true) const

このピクマップに対するヒューリスティックマスクを作成して返します。

この関数は、四隅のいずれかから色を選択し、すべてのエッジから順にその色のピクセルを削り取ることで動作します。clipTight がtrue（デフォルト）の場合、マスクはピクセルを覆うのにちょうど十分な大きさになります。そうでない場合、マスクはデータピクセルよりも大きくなります。

マスクは完璧ではないかもしれませんが、妥当な結果が得られるはずですので、次のような処理を行うことができます：

QPixmap myPixmap;
myPixmap.setMask(myPixmap.createHeuristicMask());

この関数は、QImage への変換やそこから元のデータへの変換、および非自明な計算を伴うため、処理に時間がかかります。

QImage::createHeuristicMask() およびcreateMaskFromColor()も参照してください 。

QBitmap QPixmap::createMaskFromColor(const QColor &maskColor, Qt::MaskMode mode = Qt::MaskInColor) const

指定されたmaskColor に基づいて、このピクマップ用のマスクを作成して返します。mode がQt::MaskInColor の場合、maskColorに一致するすべてのピクセルは透明になります。mode がQt::MaskOutColor の場合、maskColorに一致するすべてのピクセルは不透明になります。

この関数は、QImage との変換を伴うため、処理に時間がかかります。

createHeuristicMask() およびQImage::createMaskFromColor()も参照してください 。

[static] int QPixmap::defaultDepth()

アプリケーションで使用されるデフォルトのピクマップ深度を返します。

すべてのプラットフォームにおいて、プライマリ画面の深度が返されます。

関連項目: depth() およびPixmap Information 。

int QPixmap::depth() const

ピクマップの深度を返します。

ピクマップの深度は、ピクセルあたりのビット数 (bpp) またはピクマップのビットプレーンとも呼ばれます。ヌルピクマップの深度は 0 です。

defaultDepth() およびPixmap Informationも参照してください 。

void QPixmap::detach()

ピクマップを共有ピクマップデータから切り離します。

ピクマップの内容が変更されようとするたびに、Qt によって自動的に切り離されます。これは、ピクマップを変更するほぼすべての `QPixmap ` メンバ関数（fill()、fromImage()、load() など）および、ピクマップに対する `QPainter::begin()` 関数において行われます。

detach() を明示的に呼び出す必要がある例外が 2 つあります。それは、handle() 関数または x11PictureHandle() 関数（X11 でのみ利用可能）を呼び出す場合です。それ以外の場合、システムコールを使用して行われた変更はすべて、共有データに対して実行されます。

参照が 1 つしかない場合、またはピクマップがまだ初期化されていない場合、detach() 関数は直ちに返ります。

[since 6.2] QSizeF QPixmap::deviceIndependentSize() const

ピクマップのサイズを、デバイス非依存ピクセル単位で返します。

この値は、ユーザーインターフェースのサイズ計算でピクマップのサイズを使用する際に利用すべきです。

戻り値は、pixmap.size() / pixmap.devicePixelRatio() と同等です。

この関数は Qt 6.2 で導入されました。

qreal QPixmap::devicePixelRatio() const

ピクマップのデバイスピクセル比を返します。これは、デバイスピクセルとデバイス非依存ピクセルの比率です。

ピクマップのサイズに基づいてレイアウトのジオメトリを計算する際に、この関数を使用します：QSize layoutSize = image.size() / image.devicePixelRatio()

デフォルト値は 1.0 です。

setDevicePixelRatio() およびQImageReaderも参照してください 。

void QPixmap::fill(const QColor &color = Qt::white)

指定されたcolor でピクマップを塗りつぶします。

ピクマップへの描画処理が行われている最中、この関数の動作は未定義となります。

Pixmap Transformationsも参照してください 。

[static] QPixmap QPixmap::fromImage(const QImage &image, Qt::ImageConversionFlags flags = Qt::AutoColor)

指定されたimage を、指定されたflags を用いて変換を制御しながらピクマップに変換します。flags 引数は、Qt::ImageConversionFlags のビット単位の論理和（OR）です。flags に0を指定すると、すべてのオプションがデフォルト設定になります。

モノクロおよび8ビット画像の場合、画像はまず32ビットのピクマップに変換され、その後、カラーテーブルの色で塗りつぶされます。この処理の負荷が高すぎる場合は、代わりにQBitmap::fromImage()を使用することができます。

fromImageReader()、toImage()、およびPixmap Conversionも参照してください 。

[static] QPixmap QPixmap::fromImage(QImage &&image, Qt::ImageConversionFlags flags = Qt::AutoColor)

指定されたimage を、可能であればコピーを行わずにピクマップに変換します。

[static] QPixmap QPixmap::fromImageReader(QImageReader *imageReader, Qt::ImageConversionFlags flags = Qt::AutoColor)

imageReader から直接読み込んだ画像から、QPixmap を作成します。flags 引数は、Qt::ImageConversionFlags のビット単位のOR演算の結果です。flags に0を指定すると、すべてのデフォルトオプションが設定されます。

一部のシステムでは、画像をQPixmap に直接読み込む方が、QImage を読み込んでQPixmap に変換するよりもメモリ使用量を抑えられる場合があります。

fromImage()、toImage()、およびPixmap Conversionも参照してください 。

bool QPixmap::hasAlpha() const

このピクマップにアルファチャンネルまたはマスクがある場合は `true ` を返し、そうでない場合は `false` を返します。

hasAlphaChannel() およびmask()も参照してください 。

bool QPixmap::hasAlphaChannel() const

ピクマップのフォーマットがアルファチャンネルに対応している場合は `true ` を返し、そうでない場合は `false` を返します。

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

int QPixmap::height() const

ピクマップの高さを返します。

size() およびPixmap Informationも参照してください 。

bool QPixmap::isNull() const

これがヌルピクマップの場合は `true ` を返し、それ以外の場合は `false` を返します。

null ピクマップは、幅が 0、高さが 0 で、内容がありません。null ピクマップには描画を行うことはできません。

bool QPixmap::isQBitmap() const

これがQBitmap である場合はtrue を返し、そうでない場合はfalse を返します。

bool QPixmap::load(const QString &fileName, const char *format = nullptr, Qt::ImageConversionFlags flags = Qt::AutoColor)

指定されたfileName を持つファイルからピクマップを読み込みます。ピクマップの読み込みに成功した場合はtrueを返します。そうでない場合は、ピクマップを無効化し、false を返します。

ローダーは、指定されたformat を使用してピクマップの読み込みを試みます。format が指定されていない場合（これがデフォルトです）、ローダーはファイル内のヘッダーを調査してファイル形式を推測します。

ファイル名は、ディスク上の実際のファイル、またはアプリケーションの埋め込みリソースのいずれかを指すことができます。ピクマップやその他のリソースファイルをアプリケーションの実行ファイルに埋め込む方法の詳細については、「リソースシステムの概要」を参照してください。

データを低解像度（例えば、32 ビットから 8 ビットへの変換）に合わせて変更する必要がある場合は、flags を使用して変換を制御してください。

なお、メインスレッドでファイルから読み込まれた場合、QPixmapは自動的にQPixmapCache に追加されます。この際に使用されるキーは内部用であり、取得することはできません。

loadFromData() およびReading and Writing Image Filesも参照してください 。

bool QPixmap::loadFromData(const uchar *data, uint len, const char *format = nullptr, Qt::ImageConversionFlags flags = Qt::AutoColor)

指定されたバイナリデータ `data` の先頭 `len ` バイトからピクマップを読み込みます。ピクマップの読み込みに成功した場合は `true ` を返します。失敗した場合は、ピクマップを無効化し、`false` を返します。

ローダーは、指定されたformat を使用してピクマップの読み込みを試みます。format が指定されていない場合（これがデフォルトです）、ローダーはファイル内のヘッダーを調査してファイル形式を推測します。

データを低解像度の出力に合わせるために変更する必要がある場合（例：32ビットから8ビットへの変換）、flags を使用して変換を制御します。

load() およびReading and Writing Image Filesも参照してください 。

bool QPixmap::loadFromData(const QByteArray &data, const char *format = nullptr, Qt::ImageConversionFlags flags = Qt::AutoColor)

指定されたformat および変換flags を使用して、バイナリdata からピクマップを読み込みます。

QBitmap QPixmap::mask() const

ピクマップのアルファチャンネルからビットマップマスクを抽出します。

setMask() およびPixmap Informationも参照してください 。

QRect QPixmap::rect() const

ピクマップを囲む矩形を返します。

Pixmap Informationも参照してください 。

bool QPixmap::save(const QString &fileName, const char *format = nullptr, int quality = -1) const

指定されたfileName を使用して、指定された画像ファイルformat およびquality 係数を用いて、ピクマップをファイルに保存します。成功した場合はtrue を返し、失敗した場合はfalse を返します。

quality ファクターは、[0,100]または-1の範囲で指定する必要があります。圧縮サイズの小さいファイルを得るには0を、圧縮されていない大きなファイルを得るには100を、デフォルト設定を使用するには-1を指定します。

format がnullptr の場合、fileName の拡張子から画像形式が選択されます。

Reading and Writing Image Filesも参照してください 。

bool QPixmap::save(QIODevice *device, const char *format = nullptr, int quality = -1) const

この関数は、指定された画像ファイル `format ` および `quality ` ファクターを使用して、指定された `device ` に `QPixmap ` を書き込みます。これは、例えば、ピクマップを `QByteArray` に直接保存する場合などに使用できます：

QPixmap pixmap;
QByteArray bytes;
QBuffer buffer(&bytes);
buffer.open(QIODevice::WriteOnly);
pixmap.save(&buffer, "PNG"); // writes pixmap into bytes in PNG format

QPixmap QPixmap::scaled(const QSize &size, Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio, Qt::TransformationMode transformMode = Qt::FastTransformation) const

aspectRatioMode およびtransformMode で指定されたアスペクト比と変換モードを使用して、ピクマップを指定されたsize に拡大・縮小します。

• aspectRatioMode がQt::IgnoreAspectRatio の場合、ピクマップはsize にスケーリングされます。
• aspectRatioMode がQt::KeepAspectRatio の場合、ピクマップはアスペクト比を維持したまま、size の範囲内で可能な限り大きな長方形にスケーリングされます。
• aspectRatioMode がQt::KeepAspectRatioByExpanding の場合、ピクマップはアスペクト比を維持したまま、size の外側に収まる可能な限り小さい長方形に拡大縮小されます。

指定された `size ` が空の場合、この関数は null ピクマップを返します。

場合によっては、ピクマップをスケーリングするよりも、スケールが設定されたペインターにピクマップを描画するほうが有利なことがあります。これは、たとえばペインターが OpenGL に基づいている場合や、スケール係数が急激に変化する場合などが該当します。

isNull() およびPixmap Transformationsも参照してください 。

QPixmap QPixmap::scaled(int width, int height, Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio, Qt::TransformationMode transformMode = Qt::FastTransformation) const

指定された `width ` および `height ` に基づき、指定された `aspectRatioMode ` および `transformMode` に従って、ピクマップを矩形にスケーリングしたコピーを返します。

width またはheight のいずれかが 0 または負の値の場合、この関数は null ピクマップを返します。

QPixmap QPixmap::scaledToHeight(int height, Qt::TransformationMode mode = Qt::FastTransformation) const

画像の拡大・縮小されたコピーを返します。返される画像は、指定された変換mode を用いて、指定されたheight に拡大・縮小されます。ピクマップの縦横比が維持されるよう、ピクマップの幅は自動的に計算されます。

height が0または負の値の場合、nullのピクマップが返されます。

isNull() およびPixmap Transformationsも参照してください 。

QPixmap QPixmap::scaledToWidth(int width, Qt::TransformationMode mode = Qt::FastTransformation) const

画像の拡大・縮小されたコピーを返します。返される画像は、指定された変換mode を用いて、指定されたwidth に拡大・縮小されます。ピクマップのアスペクト比が維持されるよう、ピクマップの高さは自動的に計算されます。

width が 0 または負の値の場合、null ピクマップが返されます。

isNull() およびPixmap Transformationsも参照してください 。

void QPixmap::scroll(int dx, int dy, const QRect &rect, QRegion *exposed = nullptr)

このピクマップのrect 領域を、(dx,dy)分スクロールします。露出している領域は変更されません。オプションで、空のQRegion へのポインタを渡すことで、スクロール操作によってexposed された領域を取得することができます。

QPixmap pixmap("background.png");
QRegion exposed;
pixmap.scroll(10, 10, pixmap.rect(), &exposed);

ピクマップ上でアクティブなペインターが存在している間は、スクロールを行うことはできません。

QWidget::scroll() およびQGraphicsItem::scroll()も参照してください 。

void QPixmap::scroll(int dx, int dy, int x, int y, int width, int height, QRegion *exposed = nullptr)

この便利関数は、QPixmap::scroll(dx,dy,QRect(x,y,width,height),exposed) を呼び出すのと同じです。

QWidget::scroll() およびQGraphicsItem::scroll()も参照してください 。

void QPixmap::setDevicePixelRatio(qreal scaleFactor)

ピクマップのデバイスピクセル比を設定します。これは、画像ピクセルとデバイス非依存ピクセルの比率です。

scaleFactor のデフォルト値は1.0です。これ以外の値に設定すると、次の2つの影響があります。

ピクマップ上で開かれるQPainterはスケーリングされます。例えば、比率が2.0の場合、200x200の画像への描画は、実質的な（デバイス非依存の）描画範囲が100x100となります。

Qt内でピクマップのサイズに基づいてレイアウトのジオメトリを計算するコードパスでは、この比率が考慮されます：QSize layoutSize = pixmap.size() / pixmap.devicePixelRatio()これにより、ピクマップは大きなピクマップとしてではなく、高DPIピクマップとして表示されることになります（Drawing High Resolution Versions of Pixmaps and Images を参照）。

devicePixelRatio() およびdeviceIndependentSize()も参照してください 。

void QPixmap::setMask(const QBitmap &mask)

マスクビットマップを設定します。

この関数は、mask をピクマップのアルファチャンネルと合成します。マスク上のピクセル値が 1 の場合、ピクマップのピクセルは変更されません。値が 0 の場合、そのピクセルは透明になります。マスクは、このピクマップと同じサイズでなければなりません。

マスクを null に設定すると、マスクがリセットされ、以前に透明だったピクセルは黒になります。ピクマップへの描画が行われている最中にこの関数を実行した場合、その動作は未定義となります。

関連項目： mask()、Pixmap Transformations 、およびQBitmap 。

QSize QPixmap::size() const

ピクマップのサイズを返します。

width()、height()、およびPixmap Informationも参照してください 。

[noexcept] void QPixmap::swap(QPixmap &other)

このピクマップをother と入れ替えます。この操作は非常に高速で、失敗することはありません。

QImage QPixmap::toImage() const

ピクマップをQImage に変換します。変換に失敗した場合は、null画像を返します。

ピクマップのビット深度が1ビットの場合、返される画像のビット深度も1ビットになります。それ以上のビット深度を持つ画像は、基になるシステムに最も近い形式で返されます。通常、アルファチャンネルを持つピクマップの場合はQImage::Format_ARGB32_Premultiplied 、アルファチャンネルを持たないピクマップの場合はQImage::Format_RGB32 またはQImage::Format_RGB16 となります。

なお、現時点では、モノクロ画像のアルファマスクは無視されることに注意してください。

fromImage() およびImage Formatsも参照してください 。

QPixmap QPixmap::transformed(const QTransform &transform, Qt::TransformationMode mode = Qt::FastTransformation) const

指定された変換関数 `transform ` および `mode` を用いて変換されたピクマップのコピーを返します。元のピクマップは変更されません。

変換transform は、不要な並進を補正するために内部で調整されます。つまり、生成されるピクマップは、元のピクマップの変換後のすべての点を包含する最小のピクマップとなります。ピクマップの変換に使用された実際の行列を取得するには、trueMatrix()関数を使用してください。

この関数は、QImage への変換、複雑な計算、およびQPixmap への逆変換を伴うため、処理に時間がかかります。

trueMatrix() およびPixmap Transformationsも参照してください 。

[static] QTransform QPixmap::trueMatrix(const QTransform &matrix, int width, int height)

指定されたwidth 、height 、およびmatrix を用いてピクマップを変換するために使用された実際行列を返します。

transformed() 関数を使用してピクマップを変形する場合、不要な並進を補正するために変形行列が内部で調整されます。つまり、transformed() は、元のピクマップのすべての変形された点を包含する最小のピクマップを返します。この関数は、元のピクマップから新しいピクマップへ点を正しくマッピングする、修正後の行列を返します。

transformed() およびPixmap Transformationsも参照してください 。

int QPixmap::width() const

ピクマップの幅を返します。

size() およびPixmap Informationも参照してください 。

QPixmap::operator QVariant() const

ピクマップをQVariant として返します。

bool QPixmap::operator!() const

これがヌルピクマップの場合は `true ` を返し、それ以外の場合は `false` を返します。

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

[noexcept] QPixmap &QPixmap::operator=(QPixmap &&other)

other をこのQPixmap インスタンスに割り当てます。

QPixmap &QPixmap::operator=(const QPixmap &pixmap)

指定されたpixmap をこのピクマップに割り当て、このピクマップへの参照を返します。

copy() およびQPixmap()も参照してください 。