QImageReader Class

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

QImageReader::QImageReader()

空の QImageReader オブジェクトを生成します。画像を読み込む前に、setDevice() またはsetFileName() を呼び出してください。

[explicit] QImageReader::QImageReader(QIODevice *device, const QByteArray &format = QByteArray())

デバイスdevice および画像形式format を使用して、QImageReaderオブジェクトを生成します。

[explicit] QImageReader::QImageReader(const QString &fileName, const QByteArray &format = QByteArray())

ファイル名「fileName 」、画像形式「format 」で QImageReader オブジェクトを作成します。

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

[noexcept] QImageReader::~QImageReader()

QImageReader オブジェクトを破棄します。

[static, since 6.0] int QImageReader::allocationLimit()

現在の割り当て上限をメガバイト単位で返します。

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

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

bool QImageReader::autoDetectImageFormat() const

この画像リーダーで画像形式の自動検出が有効になっている場合は `true ` を返し、そうでない場合は `false` を返します。デフォルトでは、自動検出は有効になっています。

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

bool QImageReader::autoTransform() const

画像ハンドラが `read()` および `effectiveSize()` で変換メタデータを適用する場合、true を返します。

setAutoTransform()、transformation()、read()、およびeffectiveSize()も参照してください 。

QColor QImageReader::backgroundColor() const

画像を読み込む際に使用される背景色を返します。画像形式が背景色の設定に対応していない場合、無効な色が返されます。

setBackgroundColor() およびread()も参照してください 。

bool QImageReader::canRead() const

そのデバイスで画像を読み込める場合（つまり、画像形式がサポートされており、デバイスに有効なデータが含まれていると思われる場合）、true を返します。そうでない場合は、false を返します。

canRead() は、画像データが有効かどうかを簡単にチェックするだけの軽量な関数です。画像データが破損している場合、canRead() がtrue を返した後でも、read() は false を返すことがあります。

アニメーションをサポートする画像の場合、canRead() はすべてのフレームの読み取りが完了するとfalse を返します。

関連項目: ` read()`、`supportedImageFormats()`、および `QMimeDatabase`。

QRect QImageReader::clipRect() const

画像のクリップ矩形（ROI（Region Of Interest）とも呼ばれる）を返します。クリップ矩形が設定されていない場合は、無効なQRect が返されます。

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

int QImageReader::currentImageNumber() const

アニメーションに対応している画像形式の場合、この関数は現在のフレームのシーケンス番号を返します。画像形式がアニメーションに対応していない場合は、0 が返されます。

エラーが発生した場合は、この関数は -1 を返します。

関連項目： supportsAnimation()、QImageIOHandler::currentImageNumber()、canRead()。

QRect QImageReader::currentImageRect() const

アニメーションをサポートする画像形式の場合、この関数は現在のフレームの矩形を返します。それ以外の場合は、null の矩形が返されます。

supportsAnimation() およびQImageIOHandler::currentImageRect()も参照してください 。

bool QImageReader::decideFormatFromContent() const

画像リーダーが、ファイルの拡張子ではなく、データストリームの内容のみに基づいて使用するプラグインを決定すべきかどうかを返します。

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

QIODevice *QImageReader::device() const

QImageReader に現在割り当てられているデバイスを返します。デバイスが割り当てられていない場合は、nullptr を返します。

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

[since 6.12] QSize QImageReader::effectiveSize() const

画像の内容を実際に読み込むことなく、変形を考慮した画像の実効サイズを返します。

画像形式がこの機能をサポートしていない場合、この関数は無効なサイズを返します。Qt の組み込み画像ハンドラはすべてこの機能をサポートしていますが、カスタム画像形式プラグインについては、この機能をサポートする必要はありません。

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

関連項目： setAutoTransform()、size()、QImageIOHandler::ImageOption 、QImageIOHandler::option()、およびQImageIOHandler::supportsOption()。

QImageReader::ImageReaderError QImageReader::error() const

最後に発生したエラーのタイプを返します。

ImageReaderError およびerrorString()も参照してください 。

QString QImageReader::errorString() const

最後に発生したエラーについて、人間が理解しやすい説明を返します。

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

QString QImageReader::fileName() const

現在割り当てられているデバイスがQFile である場合、またはsetFileName()が呼び出されている場合、この関数はQImageReader が読み込むファイル名を返します。それ以外の場合（つまり、デバイスが割り当てられていないか、デバイスがQFile でない場合）、空のQString が返されます。

setFileName() およびsetDevice()も参照してください 。

QByteArray QImageReader::format() const

QImageReader が画像を読み込む際に使用するフォーマットを返します。

この関数は、リーダーにデバイスを割り当てた後に呼び出すことで、そのデバイスのフォーマットを確認できます。例：

QImageReader reader("image.png");
// reader.format() == "png"

リーダーがデバイスから画像を読み取れない場合（例えば、画像が存在しない、または画像がすでに読み取られている場合）、あるいはそのフォーマットがサポートされていない場合、この関数は空の QByteArray() を返します。

setFormat() およびsupportedImageFormats()も参照してください 。

int QImageReader::imageCount() const

アニメーションに対応している画像形式の場合、この関数はアニメーションに含まれる画像の総数を返します。その形式がアニメーションに対応していない場合は、0 が返されます。

エラーが発生した場合は、この関数は -1 を返します。

関連項目： supportsAnimation()、QImageIOHandler::imageCount()、canRead()。

QImage::Format QImageReader::imageFormat() const

画像の内容を実際に読み込むことなく、そのフォーマットを返します。このフォーマットは、QImageReader::read() が返す画像フォーマットを表すものであり、実際の画像のフォーマットではありません。

画像形式がこの機能をサポートしていない場合、この関数は無効な形式を返します。

QImageIOHandler::ImageOption 、QImageIOHandler::option()、およびQImageIOHandler::supportsOption()も参照してください 。

[static] QByteArray QImageReader::imageFormat(QIODevice *device)

サポートされている場合、この関数はデバイスの画像形式を返しますdevice 。そうでない場合は、空の文字列が返されます。

QImageReader::autoDetectImageFormat()も参照してください 。

[static] QByteArray QImageReader::imageFormat(const QString &fileName)

この関数は、サポートされている場合、ファイル `fileName` の画像形式を返します。サポートされていない場合は、空の文字列が返されます。

[static] QList<QByteArray> QImageReader::imageFormatsForMimeType(const QByteArray &mimeType)

mimeType に対応する画像形式のリストを返します。

なお、この関数を呼び出す前に、QGuiApplication のインスタンスを作成しておく必要があります。

supportedImageFormats() およびsupportedMimeTypes()も参照してください 。

bool QImageReader::jumpToImage(int imageNumber)

アニメーションをサポートする画像形式の場合、この関数はシーケンス番号が `imageNumber` の画像にスキップし、成功した場合は `true` を、対応する画像が見つからない場合は `false` を返します。

次にread() が呼び出されると、この画像の読み込みが試みられます。

jumpToNextImage() およびQImageIOHandler::jumpToImage()も参照してください 。

bool QImageReader::jumpToNextImage()

アニメーションをサポートする画像形式の場合、この関数は現在の画像を1フレーム分進め、成功した場合はtrueを、アニメーションに続く画像がない場合はfalseを返します。

デフォルトの実装では、read() を呼び出し、その結果として得られる画像を破棄しますが、画像ハンドラ側では、この操作をより効率的に実装する方法があるかもしれません。

jumpToImage() およびQImageIOHandler::jumpToNextImage()も参照してください 。

int QImageReader::loopCount() const

アニメーションをサポートする画像形式の場合、この関数はアニメーションのループ回数を返します。この関数が -1 を返した場合、アニメーションが永久にループすることを意味するか、エラーが発生したことを意味します。エラーが発生した場合は、canRead() は false を返します。

supportsAnimation()、QImageIOHandler::loopCount()、およびcanRead()も参照してください 。

int QImageReader::nextImageDelay() const

アニメーションに対応している画像形式の場合、この関数は、アニメーションの次のフレームが表示されるまで待機する時間をミリ秒単位で返します。画像形式がアニメーションに対応していない場合は、0 が返されます。

エラーが発生した場合は、この関数は -1 を返します。

関連項目： supportsAnimation()、QImageIOHandler::nextImageDelay()、およびcanRead()。

int QImageReader::quality() const

画像形式の画質設定を返します。

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

QImage QImageReader::read()

デバイスから画像を読み込みます。成功した場合は、読み込まれた画像が返されます。失敗した場合は、nullのQImage が返されます。その後、error()を呼び出して発生したエラーの種類を確認したり、errorString()を呼び出してエラーの分かりやすい説明を取得したりすることができます。

アニメーションをサポートする画像形式の場合、read() を繰り返し呼び出すと、次のフレームが返されます。すべてのフレームの読み込みが完了すると、null 画像が返されます。

canRead()、supportedImageFormats()、supportsAnimation()、およびQMovieも参照してください 。

bool QImageReader::read(QImage *image)

デバイスから画像を読み取り、`image` に格納します。` ` は `QImage` を指している必要があります。成功した場合は `true ` を返し、失敗した場合は `false` を返します。

image が、読み込もうとしている画像データと同じ形式およびサイズである場合、この関数は読み込み前に新しい画像を割り当てる必要がない場合があります。このため、常に新しい画像を構築する他のread()のオーバーロードよりも高速になる可能性があります。特に、同じ形式およびサイズの画像を複数読み込む場合にはその傾向が顕著です。

QImage icon(64, 64, QImage::Format_RGB32);
QImageReader reader("icon_64x64.bmp");
if (reader.read(&icon)) {
    // Display icon
}

アニメーションをサポートする画像形式の場合、read() を繰り返し呼び出すと、次のフレームが返されます。すべてのフレームが読み込まれると、null 画像が返されます。

canRead()、supportedImageFormats()、supportsAnimation()、およびQMovieも参照してください 。

QRect QImageReader::scaledClipRect() const

画像のスケーリングされたクリップ矩形を返します。

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

QSize QImageReader::scaledSize() const

画像のスケーリング後のサイズを返します。

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

[static, since 6.0] void QImageReader::setAllocationLimit(int mbLimit)

割り当て上限をmbLimit メガバイトに設定します。この上限を超えるQImage のメモリ割り当てを必要とする画像は拒否されます。mbLimit が0の場合、割り当てサイズのチェックは無効になります。

この制限により、アプリケーションは破損した画像ファイルの読み込みによる予期せぬ大容量のメモリ使用を回避できます。通常、この設定を変更する必要はありません。デフォルトの制限値は、一般的に使用されるすべての画像サイズに対応できる十分な大きさです。

実行時には、この値は環境変数 `QT_IMAGEIO_MAXALLOC` によって上書きされる場合があります。

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

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

void QImageReader::setAutoDetectImageFormat(bool enabled)

enabled がtrueの場合、画像形式の自動検出が有効になります。そうでない場合は無効になります。デフォルトでは、自動検出は有効になっています。

QImageReader QImageReader は、画像形式の検出に包括的なアプローチを採用しています。まず、 にファイル名を渡した場合、指定されたファイル名が既存のファイルを指していないときは、サポートされているデフォルトの拡張子を1つずつ指定されたファイル名に追加して、ファイル拡張子を検出しようと試みます。その後、以下のアプローチを用いて画像形式を検出します：

• まず、オプションのフォーマット文字列、またはファイル名のサフィックス（ソースデバイスがファイルの場合）に基づいて、画像プラグインが照会されます。この段階ではコンテンツの検出は行われません。QImageReader は、このフォーマットの読み取りをサポートする最初のプラグインを選択します。
• その画像形式をサポートするプラグインがない場合、オプションのフォーマット文字列またはファイル名の拡張子に基づいて、Qtの組み込みハンドラがチェックされます。
• 対応可能なプラグインや組み込みハンドラが見つからない場合、データストリームの内容を検査して各プラグインがテストされます。
• データの内容に基づいて画像形式を検出できるプラグインがない場合、各組み込みの画像ハンドラについて、内容を検査してテストが行われます。
• 最後に、上記のすべての方法が失敗した場合、QImageReader は画像の読み込みに失敗したと報告します。

画像形式の自動検出を無効にすると、QImageReader は形式文字列に基づいてプラグインおよび組み込みハンドラにのみ問い合わせを行います (つまり、ファイル名の拡張子はテストされません)。

autoDetectImageFormat()、QImageIOHandler::canRead()、およびQImageIOPlugin::capabilities()も参照してください 。

void QImageReader::setAutoTransform(bool enabled)

read() によって返される画像およびeffectiveSize() によって返されるサイズについては、enabled がtrue の場合、変換メタデータが自動的に適用されるようにします。

autoTransform()、transformation()、read()、およびeffectiveSize()も参照してください 。

void QImageReader::setBackgroundColor(const QColor &color)

背景色をcolor に設定します。この操作をサポートする画像形式では、画像を読み込む前に背景をcolor に初期化することが期待されます。

backgroundColor() およびread()も参照してください 。

void QImageReader::setClipRect(const QRect &rect)

画像クリップ矩形（ROI、Region Of Interest とも呼ばれる）を `rect` に設定します。rect の座標は、size() によって返される、変換前の画像サイズを基準としています。

clipRect()、setScaledSize()、およびsetScaledClipRect()も参照してください 。

void QImageReader::setDecideFormatFromContent(bool ignored)

ignored がtrueに設定されている場合、画像リーダーは指定された形式やファイル拡張子を無視し、データストリーム内の内容のみに基づいて使用するプラグインを決定します。

このフラグを設定すると、すべての画像プラグインが読み込まれます。各プラグインは、画像データの最初のバイトを読み取り、そのプラグインが互換性があるかどうかを判断します。

また、これにより画像形式の自動検出が無効になります。

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

void QImageReader::setDevice(QIODevice *device)

QImageReader のデバイスをdevice に設定します。デバイスがすでに設定されている場合、古いデバイスはQImageReader から削除されますが、それ以外は変更されません。

デバイスがまだ開かれていない場合、QImageReader は open() を呼び出して、ReadOnly モードでデバイスを開こうとします。ただし、QProcess 、QTcpSocket 、QUdpSocket などの特定のデバイスでは、デバイスを開くために追加の処理が必要となるため、この方法は機能しないことに注意してください。

device() およびsetFileName()も参照してください 。

void QImageReader::setFileName(const QString &fileName)

QImageReader のファイル名をfileName に設定します。内部的には、QImageReader はQFile オブジェクトを作成し、ReadOnly モードでそれを開き、画像の読み込み時にこれを使用します。

fileName にファイル拡張子（例：.png や .bmp）が含まれていない場合、QImageReader は、一致するファイルが見つかるまで、サポートされているすべての拡張子を順に試します。

fileName()、setDevice()、およびsupportedImageFormats()も参照してください 。

void QImageReader::setFormat(const QByteArray &format)

QImageReader が画像を読み込む際に使用する形式を、format に設定します。format は、大文字小文字を区別しないテキスト文字列です。例：

QImageReader reader;
reader.setFormat("png"); // same as reader.setFormat("PNG");

`supportedImageFormats()` を呼び出すと、QImageReader がサポートするフォーマットの完全な一覧を確認できます。

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

void QImageReader::setQuality(int quality)

画像形式の画質設定を「quality 」に設定します。

一部の画像形式、特に非可逆圧縮形式では、a) 生成される画像の視覚的品質と、b) 復号の実行時間との間でトレードオフが生じます。この関数は、それをサポートする画像形式において、そのトレードオフのレベルを設定します。

画像の拡大・縮小を行って読み込む場合、品質設定は、視覚的な品質と拡大・縮小アルゴリズムの実行速度との間のトレードオフのレベルにも影響を与える可能性があります。

quality の値の範囲は、画像形式によって異なります。例えば、「jpeg」形式では、0（視覚的品質が低い）から100（視覚的品質が高い）までの品質範囲がサポートされています。

quality() およびsetScaledSize()も参照してください 。

void QImageReader::setScaledClipRect(const QRect &rect)

スケーリング後のクリップ矩形をrect に設定します。スケーリング後のクリップ矩形とは、画像がスケーリングされた後に適用されるクリップ矩形（ROI、Region Of Interest とも呼ばれる）のことです。

scaledClipRect() およびsetScaledSize()も参照してください 。

void QImageReader::setScaledSize(const QSize &size)

画像の拡大・縮小後のサイズを `size` に設定します。拡大・縮小は、最初のクリップ矩形の処理の後、拡大・縮小後のクリップ矩形が適用される前に実行されます。 スケーリングに使用されるアルゴリズムは、画像形式によって異なります。デフォルトでは（つまり、画像形式がスケーリングをサポートしていない場合）、QImageReader はQt::SmoothScalingを使用してQImage::scale()を呼び出します。

size で1つの寸法のみが設定されている場合、アスペクト比を維持するために、もう一方の寸法は画像のnatural size から計算されます。

scaledSize()、setClipRect()、およびsetScaledClipRect()も参照してください 。

QSize QImageReader::size() const

画像の内容を実際に読み込むことなく、画像のサイズを返します。

画像形式がこの機能をサポートしていない場合、この関数は無効なサイズを返します。Qtに組み込まれている画像ハンドラはすべてこの機能をサポートしていますが、カスタム画像形式プラグインについては、この機能をサポートする必要はありません。

effectiveSize()、QImageIOHandler::ImageOption 、QImageIOHandler::option()、およびQImageIOHandler::supportsOption()も参照してください 。

QByteArray QImageReader::subType() const

画像のサブタイプを返します。

[static] QList<QByteArray> QImageReader::supportedImageFormats()

QImageReader がサポートする画像形式のリストを返します。

デフォルトでは、Qtは以下の形式を読み込むことができます:

SVG ファイルの読み書きは、 Qt SVG モジュールを通じてサポートされています。 Qt Image Formats モジュールは、その他の画像形式のサポートも提供しています。

この関数を呼び出す前に、QCoreApplication インスタンスを作成しておく必要があることに注意してください。

setFormat()、QImageWriter::supportedImageFormats()、およびQImageIOPluginも参照してください 。

[static] QList<QByteArray> QImageReader::supportedMimeTypes()

QImageReader がサポートする MIME タイプのリストを返します。

この関数を呼び出す前に、QApplication インスタンスを作成しておく必要があることに注意してください。

supportedImageFormats() およびQImageWriter::supportedMimeTypes()も参照してください 。

QList<QByteArray> QImageReader::supportedSubTypes() const

その画像でサポートされているサブタイプのリストを返します。

bool QImageReader::supportsAnimation() const

画像形式がアニメーションに対応している場合は `true ` を返し、そうでない場合は `false` を返します。

QMovie::supportedFormats()も参照してください 。

bool QImageReader::supportsOption(QImageIOHandler::ImageOption option) const

リーダーが `option` をサポートしている場合は `true ` を返し、そうでない場合は `false` を返します。

画像フォーマットによって、サポートされるオプションは異なります。 この関数を呼び出すことで、現在の形式が特定のオプションをサポートしているかどうかを判断できます。たとえば、PNG 形式では、画像のメタデータにテキストを埋め込むことができます（text() を参照）。また、BMP 形式では、画像全体をメモリに読み込まずに画像のサイズを特定することができます（size() を参照）。

QImageReader reader(":/image.png");
if(reader.supportsOption(QImageIOHandler::Size))
    qDebug() << "Size:" << reader.size();

「QImageWriter::supportsOption()」も参照してください 。

QString QImageReader::text(const QString &key) const

key に関連付けられた画像テキストを返します。

このオプションのサポートは、QImageIOHandler::Description を通じて実装されています。

textKeys() およびQImageWriter::setText()も参照してください 。

QStringList QImageReader::textKeys() const

この画像のテキストキーを返します。これらのキーを `text()` と組み合わせて使用することで、特定のキーに対応する画像テキストを一覧表示できます。

このオプションのサポートは、QImageIOHandler::Description を通じて実装されています。

text()、QImageWriter::setText()、およびQImage::textKeys()も参照してください 。

QImageIOHandler::Transformations QImageReader::transformation() const

画像の向きを含む、画像の変換メタデータを返します。フォーマットが変換メタデータをサポートしていない場合は、QImageIOHandler::TransformationNone が返されます。

setAutoTransform() およびautoTransform()も参照してください 。