En esta página

QImageWriter Class

La clase QImageWriter ofrece una interfaz independiente del formato para escribir imágenes en archivos u otros dispositivos. Más información...

Encabezado: #include <QImageWriter>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui

Nota: Todas las funciones de esta clase son reentrantes.

Tipos públicos

enum ImageWriterError { DeviceError, UnsupportedFormatError, InvalidImageError, UnknownError }

Funciones públicas

QImageWriter()
QImageWriter(QIODevice *device, const QByteArray &format)
QImageWriter(const QString &fileName, const QByteArray &format = QByteArray())
~QImageWriter()
bool canWrite() const
int compression() const
QIODevice *device() const
QImageWriter::ImageWriterError error() const
QString errorString() const
QString fileName() const
QByteArray format() const
bool optimizedWrite() const
bool progressiveScanWrite() const
int quality() const
void setCompression(int compression)
void setDevice(QIODevice *device)
void setFileName(const QString &fileName)
void setFormat(const QByteArray &format)
void setOptimizedWrite(bool optimize)
void setProgressiveScanWrite(bool progressive)
void setQuality(int quality)
void setSubType(const QByteArray &type)
void setText(const QString &key, const QString &text)
void setTransformation(QImageIOHandler::Transformations transform)
QByteArray subType() const
QList<QByteArray> supportedSubTypes() const
bool supportsOption(QImageIOHandler::ImageOption option) const
QImageIOHandler::Transformations transformation() const
bool write(const QImage &image)

Miembros públicos estáticos

QList<QByteArray> imageFormatsForMimeType(const QByteArray &mimeType)
QList<QByteArray> supportedImageFormats()
QList<QByteArray> supportedMimeTypes()

Descripción detallada

QImageWriter permite configurar opciones específicas del formato, como el nivel de compresión y la calidad, antes de guardar la imagen. Si no necesitas estas opciones, puedes utilizar en su lugar ` QImage::save()` o ` QPixmap::save()`.

Para guardar una imagen, hay que empezar por crear un objeto QImageWriter. Se debe pasar al constructor de QImageWriter un nombre de archivo o un puntero a un dispositivo, junto con el formato de la imagen. A continuación, puede establecer varias opciones, como la calidad (llamando a setQuality()). canWrite() devuelve true si QImageWriter puede escribir la imagen (es decir, si el formato de imagen es compatible y el dispositivo está abierto para la escritura). Llame a write() para escribir la imagen en el dispositivo.

Si se produce algún error al escribir la imagen, write() devolverá «false». A continuación, puede llamar a error() para averiguar el tipo de error que se ha producido, o a errorString() para obtener una descripción legible por el usuario de lo que ha fallado.

Llama a ` supportedImageFormats()` para obtener una lista de los formatos en los que QImageWriter puede escribir. QImageWriter admite todos los formatos de imagen integrados, además de cualquier complemento de formato de imagen que admita la escritura.

Nota: QImageWriter asume el control exclusivo sobre el archivo o dispositivo que se le asigne. Cualquier intento de modificar el archivo o dispositivo asignado mientras el objeto QImageWriter esté activo dará lugar a resultados indefinidos. Si se desea acceso inmediato a un recurso, se recomienda utilizar un ámbito.

Por ejemplo:

QString imagePath(QStringLiteral("path/image.jpeg"));
QImage image(64, 64, QImage::Format_RGB32);
image.fill(Qt::red);
{
    QImageWriter writer(imagePath);
    writer.write(image);
}

QFile::rename(imagePath,
              QStringLiteral("path/other_image.jpeg"));

Véase también QImageReader, QImageIOHandler, QImageIOPlugin y QColorSpace.

Documentación sobre los tipos de miembro

enum QImageWriter::ImageWriterError

Esta enumeración describe los errores que pueden producirse al guardar imágenes con QImageWriter.

ConstanteValorDescripción
QImageWriter::DeviceError1QImageWriter Se ha producido un error del dispositivo al escribir los datos de la imagen. Consulta tu dispositivo para obtener más detalles sobre el problema.
QImageWriter::UnsupportedFormatError2Qt no admite el formato de imagen solicitado.
QImageWriter::InvalidImageError3Se ha intentado escribir un ` QImage` no válido. Un ejemplo de imagen no válida sería un ` QImage` nulo.
QImageWriter::UnknownError0Se ha producido un error desconocido. Si obtienes este valor tras llamar a ` write()`, lo más probable es que se deba a un error en ` QImageWriter`.

Documentación de funciones de miembro

QImageWriter::QImageWriter()

Crea un objeto QImageWriter vacío. Antes de escribir, debes llamar a ` setFormat()` para establecer un formato de imagen y, a continuación, a ` setDevice()` o ` setFileName()`.

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

Crea un objeto QImageWriter utilizando el dispositivo device y el formato de imagen format.

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

Crea un objeto `QImageWriter` que escribirá en un archivo con el nombre ` fileName`, utilizando el formato de imagen ` format`. Si no se especifica ` format `, `QImageWriter` detectará el formato de imagen analizando la extensión de ` fileName`.

[noexcept] QImageWriter::~QImageWriter()

Destruye el objeto ` QImageWriter `.

bool QImageWriter::canWrite() const

Devuelve « true » si « QImageWriter » puede escribir la imagen; es decir, si el formato de imagen es compatible y el dispositivo asignado está abierto para la lectura.

Véase también write(), setDevice() y setFormat().

int QImageWriter::compression() const

Devuelve el nivel de compresión de la imagen.

Véase también setCompression().

QIODevice *QImageWriter::device() const

Devuelve el dispositivo asignado actualmente a QImageWriter, o nullptr si no se ha asignado ningún dispositivo.

Véase también setDevice().

QImageWriter::ImageWriterError QImageWriter::error() const

Devuelve el tipo de error que se ha producido por última vez.

Véase también ImageWriterError y errorString().

QString QImageWriter::errorString() const

Devuelve una descripción comprensible para el usuario del último error que se ha producido.

Véase también error().

QString QImageWriter::fileName() const

Si el dispositivo asignado actualmente es un archivo, o si se ha llamado a setFileName(), esta función devuelve el nombre del archivo en el que escribe QImageWriter. En caso contrario (es decir, si no se ha asignado ningún dispositivo o si el dispositivo no es un archivo), se devuelve un QString vacío.

Véanse también setFileName() y setDevice().

QByteArray QImageWriter::format() const

Devuelve el formato que utiliza QImageWriter para guardar imágenes.

Véase también setFormat().

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

Devuelve la lista de formatos de imagen correspondientes a mimeType.

Ten en cuenta que la instancia de QGuiApplication debe crearse antes de llamar a esta función.

Véanse también supportedImageFormats() y supportedMimeTypes().

bool QImageWriter::optimizedWrite() const

Devuelve si se ha activado la optimización para escribir la imagen.

Véase también setOptimizedWrite().

bool QImageWriter::progressiveScanWrite() const

Indica si la imagen debe guardarse como imagen progresiva.

Véase también setProgressiveScanWrite().

int QImageWriter::quality() const

Devuelve la configuración de calidad del formato de imagen.

Véase también setQuality().

void QImageWriter::setCompression(int compression)

Se trata de una función específica del formato de imagen que establece el nivel de compresión de una imagen. En el caso de los formatos de imagen que no admiten la configuración de la compresión, este valor se ignora.

El rango de valores de ` compression ` depende del formato de imagen:

Formato de imagenValores admitidos
PNGValores comprendidos entre 0 (sin compresión) y 100 (baja calidad visual, compresión máxima). Este valor es inverso a la calidad en setQuality. Las dos opciones son mutuamente excluyentes.
TGA0 - Sin compresión
1 - Compresión RLE
TIFF0 - Sin compresión
1 - Compresión LZW
2 - Compresión RLE
3 - Codificación de fax CCITT Grupo 3
4 - Codificación de fax CCITT Grupo 4
5 - Compresión JPEG

Véase también compression() y setQuality().

void QImageWriter::setDevice(QIODevice *device)

Establece el dispositivo de QImageWriter en device. Si ya se ha establecido un dispositivo, el antiguo se elimina de QImageWriter y, por lo demás, permanece sin cambios.

Si el dispositivo aún no está abierto, QImageWriter intentará abrirlo en modo QIODeviceBase::WriteOnly llamando a open(). Ten en cuenta que esto no funciona con determinados dispositivos, como QProcess, QTcpSocket y QUdpSocket, en los que se requiere una lógica más compleja para abrir el dispositivo.

Véanse también device() y setFileName().

void QImageWriter::setFileName(const QString &fileName)

Establece el nombre del archivo de « QImageWriter » en « fileName ». Internamente, « QImageWriter » creará un archivo « QFile » y lo abrirá en modo « QIODevice::WriteOnly », y utilizará este archivo al escribir imágenes.

Véase también fileName() y setDevice().

void QImageWriter::setFormat(const QByteArray &format)

Establece el formato que utilizará QImageWriter al generar imágenes: format. format es una cadena de texto que no distingue entre mayúsculas y minúsculas. Ejemplo:

QImageWriter writer;
writer.setFormat("png"); // same as writer.setFormat("PNG");

Puedes llamar a ` supportedImageFormats()` para obtener la lista completa de formatos que admite ` QImageWriter `.

Véase también format().

void QImageWriter::setOptimizedWrite(bool optimize)

Esta es una función específica del formato de imagen que establece los indicadores « optimize » al guardar imágenes. En el caso de los formatos de imagen que no admiten la configuración del indicador « optimize », este valor se ignora.

El valor por defecto es false.

Véase también optimizedWrite().

void QImageWriter::setProgressiveScanWrite(bool progressive)

Esta es una función específica del formato de imagen que activa el escaneado « progressive » al escribir imágenes. En el caso de los formatos de imagen que no admiten la configuración de un indicador de escaneado « progressive », este valor se ignora.

El valor por defecto es false.

Véase también progressiveScanWrite().

void QImageWriter::setQuality(int quality)

Establece la configuración de calidad del formato de imagen en « quality ».

Algunos formatos de imagen, en particular los que admiten pérdida de información, implican un equilibrio entre: a) la calidad visual de la imagen resultante, y b) el tiempo de ejecución de la codificación y el nivel de compresión. Esta función establece el nivel de dicho equilibrio para los formatos de imagen que lo admiten. Para otros formatos, este valor se ignora.

El rango de valores de ` quality ` depende del formato de imagen. Por ejemplo, el formato «jpeg» admite un rango de calidad que va de 0 (baja calidad visual, alta compresión) a 100 (alta calidad visual, baja compresión).

Véase también quality().

void QImageWriter::setSubType(const QByteArray &type)

Se trata de una función específica del formato de imagen que establece el subtipo de la imagen en « type ». Un controlador puede utilizar el subtipo para determinar qué formato debe emplear al guardar la imagen.

Por ejemplo, para guardar una imagen en formato DDS con el subtipo A8R8G8R8:

QImageWriter writer("some/image.dds");
if (writer.supportsOption(QImageIOHandler::SubType))
    writer.setSubType("A8R8G8B8");
writer.write(image);

Véase también subType().

void QImageWriter::setText(const QString &key, const QString &text)

Establece el texto de la imagen asociado a la clave « key » como « text ». Esto resulta útil para almacenar información sobre los derechos de autor u otros datos relacionados con la imagen. Ejemplo:

QImage image("some/image.jpeg");
QImageWriter writer("images/outimage.png", "png");
writer.setText("Author", "John Smith");
writer.write(image);

Si deseas almacenar un único bloque de datos (por ejemplo, un comentario), puedes pasar una clave vacía o utilizar una clave genérica como «Description».

La clave y el texto se incrustarán en los datos de la imagen tras llamar a write().

La compatibilidad con esta opción se implementa a través de QImageIOHandler::Description.

Véanse también QImage::setText() y QImageReader::text().

void QImageWriter::setTransformation(QImageIOHandler::Transformations transform)

Establece los metadatos de las transformaciones de la imagen, incluida la orientación, en transform.

Si el formato de imagen no admite los metadatos de transformación, la transformación se aplica antes de la escritura.

Véase también transformation() y write().

QByteArray QImageWriter::subType() const

Devuelve el subtipo de la imagen.

Véase también setSubType().

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

Devuelve la lista de formatos de imagen compatibles con QImageWriter.

Por defecto, Qt puede escribir en los siguientes formatos:

FormatoTipo MIMEDescripción
BMPimage/bmpMapa de bits de Windows
JPGimage/jpegGrupo Conjunto de Expertos Fotográficos
PNGimage/pngGráficos de red portátiles
PBMimage/x-portable-bitmapMapa de bits portátil
PGMimage/x-portable-graymapMapa de grises portátil
PPMimage/x-portable-pixmapMapa de píxeles portátil
XBMimage/x-xbitmapMapa de píxeles X11
XPMimagen/x-xpixmapMapa de píxeles X11

La lectura y escritura de archivos SVG se admite a través del Qt SVG módulo. El Qt Image Formats módulo ofrece compatibilidad con formatos de imagen adicionales.

Ten en cuenta que la instancia de ` QApplication ` debe crearse antes de llamar a esta función.

Véase también setFormat(), QImageReader::supportedImageFormats() y QImageIOPlugin.

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

Devuelve la lista de tipos MIME compatibles con QImageWriter.

Ten en cuenta que la instancia de QApplication debe crearse antes de llamar a esta función.

Véanse también supportedImageFormats() y QImageReader::supportedMimeTypes().

QList<QByteArray> QImageWriter::supportedSubTypes() const

Devuelve la lista de subtipos compatibles con una imagen.

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

Devuelve « true » si el escritor admite « option »; en caso contrario, devuelve «false».

Los distintos formatos de imagen admiten diferentes opciones. Llama a esta función para determinar si el formato actual admite una opción determinada. Por ejemplo, el formato PNG permite incrustar texto en los metadatos de la imagen (véase text()).

QImageWriter writer(fileName);
if (writer.supportsOption(QImageIOHandler::Description))
    writer.setText("Author", "John Smith");

Las opciones se pueden comprobar una vez que el escritor se haya asociado a un formato.

Véanse también QImageReader::supportsOption() y setFormat().

QImageIOHandler::Transformations QImageWriter::transformation() const

Devuelve la transformación y la orientación con las que se ha configurado la imagen.

Véase también setTransformation().

bool QImageWriter::write(const QImage &image)

Escribe la imagen image en el dispositivo o archivo asignado. Devuelve true si la operación se realiza correctamente; en caso contrario, devuelve false. Si la operación falla, puedes llamar a error() para averiguar el tipo de error que se ha producido, o a errorString() para obtener una descripción del error en un formato legible para el usuario.

Véase también canWrite(), error() y errorString().

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.