En esta página

QImage Class

La clase QImage ofrece una representación de imágenes independiente del hardware que permite el acceso directo a los datos de los píxeles y puede utilizarse como dispositivo de dibujo. Más...

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

Nota: Todas las funciones de esta clase son reentrantes.

Tipos públicos

enum Format { Format_Invalid, Format_Mono, Format_MonoLSB, Format_Indexed8, Format_RGB32, …, Format_CMYK8888 }
enum InvertMode { InvertRgb, InvertRgba }

Funciones públicas

QImage()
QImage(const char *const[] xpm)
QImage(const QSize &size, QImage::Format format)
QImage(const QString &fileName, const char *format = nullptr)
QImage(int width, int height, QImage::Format format)
QImage(const uchar *data, int width, int height, QImage::Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr)
QImage(uchar *data, int width, int height, QImage::Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr)
QImage(const uchar *data, int width, int height, qsizetype bytesPerLine, QImage::Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr)
QImage(uchar *data, int width, int height, qsizetype bytesPerLine, QImage::Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr)
QImage(const QImage &image)
QImage(QImage &&other)
virtual ~QImage()
bool allGray() const
void applyColorTransform(const QColorTransform &transform)
(since 6.8) void applyColorTransform(const QColorTransform &transform, QImage::Format toFormat, Qt::ImageConversionFlags flags = Qt::AutoColor)
int bitPlaneCount() const
uchar *bits()
const uchar *bits() const
qsizetype bytesPerLine() const
qint64 cacheKey() const
QRgb color(int i) const
int colorCount() const
QColorSpace colorSpace() const
QList<QRgb> colorTable() const
(since 6.4) QImage colorTransformed(const QColorTransform &transform) const &
(since 6.8) QImage colorTransformed(const QColorTransform &transform, QImage::Format toFormat, Qt::ImageConversionFlags flags = Qt::AutoColor) const &
(since 6.4) QImage colorTransformed(const QColorTransform &transform) &&
(since 6.8) QImage colorTransformed(const QColorTransform &transform, QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) &&
const uchar *constBits() const
const uchar *constScanLine(int i) const
void convertTo(QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor)
void convertToColorSpace(const QColorSpace &colorSpace)
(since 6.8) void convertToColorSpace(const QColorSpace &colorSpace, QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor)
QImage convertToFormat(QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) &&
QImage convertToFormat(QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) const &
QImage convertToFormat(QImage::Format format, const QList<QRgb> &colorTable, Qt::ImageConversionFlags flags = Qt::AutoColor) const
(since 6.0) QImage convertedTo(QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) &&
(since 6.0) QImage convertedTo(QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) const &
QImage convertedToColorSpace(const QColorSpace &colorSpace) const
(since 6.8) QImage convertedToColorSpace(const QColorSpace &colorSpace, QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) &&
(since 6.8) QImage convertedToColorSpace(const QColorSpace &colorSpace, QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) const &
QImage copy(const QRect &rectangle = QRect()) const
QImage copy(int x, int y, int width, int height) const
QImage createAlphaMask(Qt::ImageConversionFlags flags = Qt::AutoColor) const
QImage createHeuristicMask(bool clipTight = true) const
QImage createMaskFromColor(QRgb color, Qt::MaskMode mode = Qt::MaskInColor) const
int depth() const
(since 6.2) QSizeF deviceIndependentSize() const
qreal devicePixelRatio() const
int dotsPerMeterX() const
int dotsPerMeterY() const
void fill(uint pixelValue)
void fill(Qt::GlobalColor color)
void fill(const QColor &color)
(since 6.9) void flip(Qt::Orientations orient = Qt::Vertical)
(since 6.9) QImage flipped(Qt::Orientations orient = Qt::Vertical) &&
(since 6.9) QImage flipped(Qt::Orientations orient = Qt::Vertical) const &
QImage::Format format() const
bool hasAlphaChannel() const
int height() const
void invertPixels(QImage::InvertMode mode = InvertRgb)
bool isGrayscale() const
bool isNull() const
bool load(const QString &fileName, const char *format = nullptr)
bool load(QIODevice *device, const char *format)
(since 6.2) bool loadFromData(QByteArrayView data, const char *format = nullptr)
bool loadFromData(const QByteArray &data, const char *format = nullptr)
bool loadFromData(const uchar *data, int len, const char *format = nullptr)
(since 6.0, until 6.13) void mirror(bool horizontal = false, bool vertical = true)
(until 6.13) QImage mirrored(bool horizontal = false, bool vertical = true) &&
(until 6.13) QImage mirrored(bool horizontal = false, bool vertical = true) const &
QPoint offset() const
QRgb pixel(const QPoint &position) const
QRgb pixel(int x, int y) const
QColor pixelColor(const QPoint &position) const
QColor pixelColor(int x, int y) const
QPixelFormat pixelFormat() const
int pixelIndex(const QPoint &position) const
int pixelIndex(int x, int y) const
QRect rect() const
bool reinterpretAsFormat(QImage::Format format)
(since 6.0) void rgbSwap()
QImage rgbSwapped() &&
QImage rgbSwapped() const &
bool save(const QString &fileName, const char *format = nullptr, int quality = -1) const
bool save(QIODevice *device, const char *format = nullptr, int quality = -1) const
QImage scaled(const QSize &size, Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio, Qt::TransformationMode transformMode = Qt::FastTransformation) const
QImage scaled(int width, int height, Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio, Qt::TransformationMode transformMode = Qt::FastTransformation) const
QImage scaledToHeight(int height, Qt::TransformationMode mode = Qt::FastTransformation) const
QImage scaledToWidth(int width, Qt::TransformationMode mode = Qt::FastTransformation) const
uchar *scanLine(int i)
const uchar *scanLine(int i) const
void setAlphaChannel(const QImage &alphaChannel)
void setColor(int index, QRgb colorValue)
void setColorCount(int colorCount)
void setColorSpace(const QColorSpace &colorSpace)
void setColorTable(const QList<QRgb> &colors)
void setDevicePixelRatio(qreal scaleFactor)
void setDotsPerMeterX(int x)
void setDotsPerMeterY(int y)
void setOffset(const QPoint &offset)
void setPixel(const QPoint &position, uint index_or_rgb)
void setPixel(int x, int y, uint index_or_rgb)
void setPixelColor(const QPoint &position, const QColor &color)
void setPixelColor(int x, int y, const QColor &color)
void setText(const QString &key, const QString &text)
QSize size() const
qsizetype sizeInBytes() const
void swap(QImage &other)
QString text(const QString &key = QString()) const
QStringList textKeys() const
CGImageRef toCGImage() const
(since 6.0) HBITMAP toHBITMAP() const
(since 6.0) HICON toHICON(const QImage &mask = {}) const
QImage transformed(const QTransform &matrix, Qt::TransformationMode mode = Qt::FastTransformation) const
bool valid(const QPoint &pos) const
bool valid(int x, int y) const
int width() const
operator QVariant() const
bool operator!=(const QImage &image) const
QImage &operator=(QImage &&other)
QImage &operator=(const QImage &image)
bool operator==(const QImage &image) const

Miembros públicos estáticos

(since 6.2) QImage fromData(QByteArrayView datos, const char*formato = nullptr)
QImage fromData(const QByteArray&data, const char*format = nullptr)
QImage fromData(const uchar*datos, int tamaño, const char*formato = nullptr)
(since 6.0) QImage fromHBITMAP(HBITMAP hbitmap)
(since 6.0) QImage fromHICON(HICON icon)
QImage::Format toImageFormat(QPixelFormat formato)
QPixelFormat toPixelFormat( formato QImage::Format)
QTransform trueMatrix(const QTransform&matrix, int width, int height)
QImageCleanupFunction
QDataStream &operator<<(QDataStream &stream, const QImage &image)
QDataStream &operator>>(QDataStream &stream, QImage &image)

Descripción detallada

Qt proporciona cuatro clases para gestionar datos de imagen: QImage, QPixmap, QBitmap y QPicture. QImage está diseñada y optimizada para E/S, así como para el acceso directo a los píxeles y su manipulación, mientras que QPixmap está diseñada y optimizada para mostrar imágenes en pantalla. QBitmap es únicamente una clase de conveniencia que hereda de QPixmap, lo que garantiza una profundidad de 1. Por último, la clase QPicture es un dispositivo de dibujo que graba y reproduce comandos QPainter.

Dado que QImage es una subclase de QPaintDevice, QPainter se puede utilizar para dibujar directamente sobre imágenes. Al utilizar QPainter en un QImage, el dibujo se puede realizar en un hilo distinto al hilo actual de la interfaz gráfica de usuario.

La clase QImage admite varios formatos de imagen descritos por la enumeración Format. Entre ellos se incluyen imágenes monocromáticas, de 8 bits, de 32 bits y con mezcla alfa, que están disponibles en todas las versiones de Qt 4.x.

QImage proporciona un conjunto de funciones que pueden utilizarse para obtener diversa información sobre la imagen. También hay varias funciones que permiten transformar la imagen.

Los objetos QImage se pueden pasar por valor, ya que la clase QImage utiliza el intercambio implícito de datos. Los objetos QImage también se pueden transmitir y comparar.

Nota: Si deseas cargar objetos QImage en una compilación estática de Qt, consulta la guía práctica sobre complementos.

Advertencia: No se admitepintar sobre un QImage con el formato QImage::Format_Indexed8 o QImage::Format_CMYK8888.

Lectura y escritura de archivos de imagen

QImage ofrece varias formas de cargar un archivo de imagen: el archivo se puede cargar al crear el objeto QImage o utilizando posteriormente las funciones ` load()` o ` loadFromData()`. QImage también proporciona la función estática fromData(), que crea un objeto QImage a partir de los datos proporcionados. Al cargar una imagen, el nombre del archivo puede hacer referencia a un archivo real en el disco o a uno de los recursos incrustados de la aplicación. Consulte la descripción general del sistema de recursos de Qt para obtener más detalles sobre cómo incrustar imágenes y otros archivos de recursos en el ejecutable de la aplicación.

Basta con llamar a la función ` save()` para guardar un objeto `QImage`.

La lista completa de formatos de archivo compatibles está disponible a través de las funciones ` QImageReader::supportedImageFormats()` y ` QImageWriter::supportedImageFormats()`. Se pueden añadir nuevos formatos de archivo como complementos. De forma predeterminada, Qt admite los siguientes formatos:

FormatoDescripciónCompatibilidad de Qt
BMPMapa de bits de WindowsLectura/escritura
GIFFormato de intercambio de gráficos (opcional)Lectura
JPGGrupo Conjunto de Expertos FotográficosLectura/escritura
JPEGGrupo Conjunto de Expertos FotográficosLectura/escritura
PNGGráficos de red portátilesLectura/escritura
PBMMapa de bits portátilLectura
PGMMapa de grises portátilLeer
PPMMapa de píxeles portátilLectura/escritura
XBMMapa de bits X11Lectura/escritura
XPMMapa de píxeles X11Lectura/escritura

Información de la imagen

QImage proporciona un conjunto de funciones que pueden utilizarse para obtener diversa información sobre la imagen:

Funciones disponibles
GeometríaLas funciones ` size()`, ` width()`, ` height()`, ` dotsPerMeterX()` y ` dotsPerMeterY()` proporcionan información sobre el tamaño y la relación de aspecto de la imagen.

La función rect() devuelve el rectángulo que enmarca la imagen. La función valid() indica si un par de coordenadas dado se encuentra dentro de este rectángulo. La función offset() devuelve el número de píxeles en el que se pretende desplazar la imagen al posicionarla en relación con otras imágenes, lo que también se puede manipular mediante la función setOffset().

ColoresEl color de un píxel se puede obtener pasando sus coordenadas a la función pixel(). La función pixel() devuelve el color como un valor QRgb, independientemente del formato de la imagen.

En el caso de imágenes monocromáticas y de 8 bits, las funciones ` colorCount()` y ` colorTable()` proporcionan información sobre los componentes de color utilizados para almacenar los datos de la imagen: La función ` colorTable()` devuelve la tabla de colores completa de la imagen. Para obtener una sola entrada, utiliza la función pixelIndex() para recuperar el índice de píxel correspondiente a un par de coordenadas determinado y, a continuación, utiliza la función color() para recuperar el color. Ten en cuenta que, si creas una imagen de 8 bits manualmente, también debes establecer una tabla de colores válida en la imagen.

La función ` hasAlphaChannel()` indica si el formato de la imagen respeta el canal alfa o no. Las funciones ` allGray()` y ` isGrayscale()` indican si todos los colores de una imagen son tonos de gris.

Véanse también las secciones « Pixel Manipulation » y « Image Transformations ».

TextoLa función text() devuelve el texto de la imagen asociado a la clave de texto dada. Las claves de texto de una imagen se pueden recuperar mediante la función textKeys(). Utiliza la función setText() para modificar el texto de una imagen.
Información de bajo nivelLa función ` depth()` devuelve la profundidad de la imagen. Las profundidades admitidas son 1 (monocromo), 8, 16, 24 y 32 bits. La función ` bitPlaneCount()` indica cuántos de esos bits se utilizan. Para obtener más información, consulte la sección ` Image Formats `.

Las funciones format(), bytesPerLine() y sizeInBytes() proporcionan información de bajo nivel sobre los datos almacenados en la imagen.

La función cacheKey() devuelve un número que identifica de forma única el contenido de este objeto QImage.

Manipulación de píxeles

Las funciones utilizadas para manipular los píxeles de una imagen dependen del formato de la imagen. El motivo es que las imágenes monocromáticas y de 8 bits se basan en índices y utilizan una tabla de consulta de colores, mientras que las imágenes de 32 bits almacenan valores ARGB directamente. Para obtener más información sobre los formatos de imagen, consulta la sección « Image Formats ».

En el caso de una imagen de 32 bits, la función ` setPixel()` se puede utilizar para cambiar el color del píxel situado en las coordenadas indicadas por cualquier otro color especificado como un cuádruplet ARGB. Para obtener un valor « QRgb » adecuado, utilice la función « qRgb()» (que añade un componente alfa predeterminado a los valores RGB indicados, es decir, crea un color opaco) o la función « qRgba()». Por ejemplo:

32 bits
Cuadrícula de 3x3 píxeles con valores de color ARGB
QImage image(3, 3, QImage::Format_RGB32);
QRgb value;

value = qRgb(189, 149, 39); // 0xffbd9527
image.setPixel(1, 1, value);

value = qRgb(122, 163, 39); // 0xff7aa327
image.setPixel(0, 1, value);
image.setPixel(1, 0, value);

value = qRgb(237, 187, 51); // 0xffedba31
image.setPixel(2, 1, value);

En el caso de imágenes de 8 bits y monocromáticas, el valor del píxel es únicamente un índice de la tabla de colores de la imagen. Por lo tanto, la función setPixel() solo puede utilizarse para cambiar el color del píxel en las coordenadas indicadas por un color predefinido de la tabla de colores de la imagen; es decir, solo puede modificar el valor del índice del píxel. Para modificar o añadir un color a la tabla de colores de una imagen, utiliza la función setColor().

Una entrada de la tabla de colores es un cuádruplete ARGB codificado como un valor ` QRgb `. Utiliza las funciones ` qRgb()` y ` qRgba()` para generar un valor ` QRgb ` adecuado para su uso con la función ` setColor()`. Por ejemplo:

8 bits
Cuadrícula de 3x3 píxeles con colores indexados y tabla de colores
QImage image(3, 3, QImage::Format_Indexed8);
QRgb value;

value = qRgb(122, 163, 39); // 0xff7aa327
image.setColor(0, value);

value = qRgb(237, 187, 51); // 0xffedba31
image.setColor(1, value);

value = qRgb(189, 149, 39); // 0xffbd9527
image.setColor(2, value);

image.setPixel(0, 1, 0);
image.setPixel(1, 0, 0);
image.setPixel(1, 1, 2);
image.setPixel(2, 1, 1);

Para imágenes con más de 8 bits por canal de color. Los métodos setPixelColor() y pixelColor() pueden utilizarse para establecer y obtener valores QColor.

QImage también proporciona la función scanLine(), que devuelve un puntero a los datos del píxel en la línea de exploración con el índice dado, y la función bits(), que devuelve un puntero a los datos del primer píxel (esto equivale a scanLine(0)).

Formatos de imagen

Cada píxel almacenado en un QImage se representa mediante un entero. El tamaño del entero varía en función del formato. QImage admite varios formatos de imagen descritos por la enumeración Format.

Las imágenes monocromáticas se almacenan utilizando índices de 1 bit en una tabla de colores con un máximo de dos colores. Existen dos tipos diferentes de imágenes monocromáticas: con orden de bits «big endian» (MSB primero) o «little endian» (LSB primero).

Las imágenes de 8 bits se almacenan mediante índices de 8 bits en una tabla de colores, es decir, tienen un solo byte por píxel. La tabla de colores es un QList<QRgb>, y la definición de tipo QRgb es equivalente a un unsigned int que contiene un cuádruplete ARGB en el formato 0xAARRGGBB.

Las imágenes de 32 bits no tienen tabla de colores; en su lugar, cada píxel contiene un valor de tipo « QRgb ». Existen tres tipos diferentes de imágenes de 32 bits que almacenan valores RGB (es decir, 0xffRRGGBB), ARGB y ARGB premultiplicado, respectivamente. En el formato premultiplicado, los canales de rojo, verde y azul se multiplican por el componente alfa dividido entre 255.

El formato de una imagen se puede obtener mediante la función ` format()`. Utiliza las funciones ` convertToFormat()` para convertir una imagen a otro formato. Las funciones ` allGray()` y ` isGrayscale()` indican si una imagen en color se puede convertir de forma segura a una imagen en escala de grises.

Transformaciones de imágenes

QImage admite varias funciones para crear una nueva imagen que sea una versión transformada de la original: la función ` createAlphaMask()` crea y devuelve una máscara de 1 bpp a partir del búfer alfa de esta imagen, y la función ` createHeuristicMask()` crea y devuelve una máscara heurística de 1 bpp para esta imagen. Esta última función funciona seleccionando un color de una de las esquinas y, a continuación, eliminando píxeles de ese color empezando por todos los bordes.

La función ` mirrored()` devuelve una imagen reflejada en la dirección deseada; la función ` scaled()` devuelve una copia de la imagen escalada a un rectángulo de las dimensiones deseadas; y la función ` rgbSwapped()` construye una imagen BGR a partir de una imagen RGB.

Las funciones ` scaledToWidth()` y ` scaledToHeight()` devuelven copias escaladas de la imagen.

La función transformed() devuelve una copia de la imagen transformada con la matriz de transformación y el modo de transformación indicados: internamente, la matriz de transformación se ajusta para compensar cualquier traslación no deseada; es decir, transformed() devuelve la imagen más pequeña que contiene todos los puntos transformados de la imagen original. La función estática trueMatrix() devuelve la matriz real utilizada para transformar la imagen.

También hay funciones para modificar los atributos de una imagen in situ:

FunciónDescripción
setDotsPerMeterX()Define la relación de aspecto estableciendo el número de píxeles que caben horizontalmente en un metro físico.
setDotsPerMeterY()Define la relación de aspecto estableciendo el número de píxeles que caben verticalmente en un metro físico.
fill()Rellena toda la imagen con el valor de píxel indicado.
invertPixels()Invierte todos los valores de píxel de la imagen utilizando el valor de « InvertMode » especificado.
setColorTable()Establece la tabla de colores utilizada para convertir los índices de color. Solo formatos monocromáticos y de 8 bits.
setColorCount()Cambia el tamaño de la tabla de colores. Solo formatos monocromáticos y de 8 bits.

Véase también QImageReader, QImageWriter, QPixmap, QSvgRenderer, Ejemplo de composición de imágenes y Ejemplo de garabatos.

Documentación sobre tipos de miembros

enum QImage::Format

En Qt están disponibles los siguientes formatos de imagen. Consulta las notas que aparecen tras la tabla.

ConstanteValorDescripción
QImage::Format_Invalid0La imagen no es válida.
QImage::Format_Mono1La imagen se almacena utilizando 1 bit por píxel. Los bytes se empaquetan con el bit más significativo (MSB) primero.
QImage::Format_MonoLSB2La imagen se almacena utilizando 1 bit por píxel. Los bytes se empaquetan con el bit menos significativo (LSB) primero.
QImage::Format_Indexed83La imagen se almacena utilizando índices de 8 bits en un mapa de colores.
QImage::Format_RGB324La imagen se almacena utilizando un formato RGB de 32 bits (0xffRRGGBB).
QImage::Format_ARGB325La imagen se almacena utilizando un formato ARGB de 32 bits (0xAARRGGBB).
QImage::Format_ARGB32_Premultiplied6La imagen se almacena utilizando un formato ARGB de 32 bits premultiplicado (0xAARRGGBB); es decir, los canales de rojo, verde y azul se multiplican por el componente alfa dividido entre 255. (Si RR, GG o BB tienen un valor superior al del canal alfa, los resultados son indefinidos). Ciertas operaciones (como la composición de imágenes mediante mezcla alfa) son más rápidas utilizando ARGB32 premultiplicado que con ARGB32 simple.
QImage::Format_RGB167La imagen se almacena en un formato RGB de 16 bits (5-6-5).
QImage::Format_ARGB8565_Premultiplied8La imagen se almacena utilizando un formato ARGB de 24 bits premultiplicado (8-5-6-5).
QImage::Format_RGB6669La imagen se almacena en un formato RGB de 24 bits (6-6-6). Los bits más significativos no utilizados son siempre cero.
QImage::Format_ARGB6666_Premultiplied10La imagen se almacena utilizando un formato ARGB de 24 bits premultiplicado (6-6-6-6).
QImage::Format_RGB55511La imagen se almacena en formato RGB de 16 bits (5-5-5). El bit más significativo no utilizado es siempre cero.
QImage::Format_ARGB8555_Premultiplied12La imagen se almacena en formato ARGB de 24 bits premultiplicado (8-5-5-5).
QImage::Format_RGB88813La imagen se almacena en formato RGB de 24 bits (8-8-8).
QImage::Format_RGB44414La imagen se almacena en un formato RGB de 16 bits (4-4-4). Los bits no utilizados son siempre cero.
QImage::Format_ARGB4444_Premultiplied15La imagen se almacena en formato ARGB de 16 bits premultiplicado (4-4-4-4).
QImage::Format_RGBX8888 (since Qt 5.2)16La imagen se almacena utilizando un formato RGB(x) de 32 bits con orden de bytes (8-8-8-8). Es igual que el Format_RGBA8888, salvo que el canal alfa debe ser siempre 255.
QImage::Format_RGBA8888 (since Qt 5.2)17La imagen se almacena utilizando un formato RGBA de 32 bits con orden de bytes (8-8-8-8).
QImage::Format_RGBA8888_Premultiplied (since Qt 5.2)18La imagen se almacena en formato RGBA de 32 bits con orden de bytes y premultiplicado (8-8-8-8).
QImage::Format_BGR30 (since Qt 5.4)19La imagen se almacena en formato BGR de 32 bits (x-10-10-10).
QImage::Format_A2BGR30_Premultiplied (since Qt 5.4)20La imagen se almacena utilizando un formato ABGR de 32 bits premultiplicado (2-10-10-10).
QImage::Format_RGB30 (since Qt 5.4)21La imagen se almacena en formato RGB de 32 bits (x-10-10-10).
QImage::Format_A2RGB30_Premultiplied (since Qt 5.4)22La imagen se almacena en formato ARGB premultiplicado de 32 bits (2-10-10-10).
QImage::Format_Alpha8 (since Qt 5.5)23La imagen se almacena en un formato de 8 bits solo alfa.
QImage::Format_Grayscale8 (since Qt 5.5)24La imagen se almacena en un formato de escala de grises de 8 bits.
QImage::Format_Grayscale16 (since Qt 5.13)28La imagen se almacena en formato de escala de grises de 16 bits.
QImage::Format_RGBX64 (since Qt 5.12)25La imagen se almacena utilizando un formato RGB(x) de 64 bits con orden de media palabra (16-16-16-16). Es igual que el Format_RGBA64, salvo que el canal alfa debe ser siempre 65535.
QImage::Format_RGBA64 (since Qt 5.12)26La imagen se almacena en un formato RGBA de 64 bits con orden de media palabra (16-16-16-16).
QImage::Format_RGBA64_Premultiplied (since Qt 5.12)27La imagen se almacena utilizando un formato RGBA de 64 bits con orden de medio palabra y premultiplicado (16-16-16-16).
QImage::Format_BGR888 (since Qt 5.14)29La imagen se almacena utilizando un formato BGR de 24 bits.
QImage::Format_RGBX16FPx4 (since Qt 6.2)30La imagen se almacena utilizando un formato RGBx de cuatro «halfwords» de 16 bits en coma flotante (16FP-16FP-16FP-16FP). Es igual que el Format_RGBA16FPx4, salvo que el canal alfa debe ser siempre 1,0.
QImage::Format_RGBA16FPx4 (since Qt 6.2)31La imagen se almacena utilizando un formato RGBA de cuatro «halfword» de 16 bits en coma flotante (16FP-16FP-16FP-16FP).
QImage::Format_RGBA16FPx4_Premultiplied (since Qt 6.2)32La imagen se almacena utilizando un formato RGBA de cuatro «halfwords» de 16 bits en coma flotante premultiplicado (16FP-16FP-16FP-16FP).
QImage::Format_RGBX32FPx4 (since Qt 6.2)33La imagen se almacena utilizando un formato RGBx de cuatro «halfwords» de 32 bits en coma flotante (32FP-32FP-32FP-32FP). Es idéntico al Format_RGBA32FPx4, salvo que el alfa debe ser siempre 1,0.
QImage::Format_RGBA32FPx4 (since Qt 6.2)34La imagen se almacena utilizando un formato RGBA de cuatro mitades de palabra de 32 bits en coma flotante (32FP-32FP-32FP-32FP).
QImage::Format_RGBA32FPx4_Premultiplied (since Qt 6.2)35La imagen se almacena utilizando un formato RGBA de cuatro valores de 32 bits en coma flotante premultiplicados (32FP-32FP-32FP-32FP).
QImage::Format_CMYK8888 (since Qt 6.8)36La imagen se almacena utilizando un formato CMYK de 32 bits con orden de bytes.

Los formatos con orden de bytes tienen una « QPixelFormat::typeInterpretation » () de QPixelFormat::UnsignedByte, lo que significa que los componentes de color individuales se almacenan en memoria en un orden fijo, por ejemplo, 0xRR, 0xGG, 0xBB, 0xAA, independientemente del endianismo de la plataforma. Estos formatos deben leerse como bytes individuales o interpretarse como QPixelFormat::BigEndian si se leen en bloques más grandes.

Nota: No se admiteel dibujo en un ` QImage ` con el formato `QImage::Format_Indexed8` o `QImage::Format_CMYK8888`.

Nota: Evita renderizar directamente a la mayoría de estos formatos utilizando QPainter. El renderizado está optimizado principalmente para los formatos Format_RGB32 y Format_ARGB32_Premultiplied, y en segundo lugar para los formatos Format_RGB16, Format_RGBX8888, Format_RGBA8888_Premultiplied, Format_RGBX64 y Format_RGBA64_Premultiplied

Véase también format() y convertToFormat().

enum QImage::InvertMode

Este tipo de enumeración se utiliza para describir cómo deben invertirse los valores de los píxeles en la función invertPixels().

ConstanteValorDescripción
QImage::InvertRgb0Invierte únicamente los valores RGB y deja el canal alfa sin cambios.
QImage::InvertRgba1Invierte todos los canales, incluido el canal alfa.

Véase también invertPixels().

Documentación de funciones de miembro

[noexcept] QImage::QImage()

Crea una imagen nula.

Véase también isNull().

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

Crea una imagen a partir de la imagen « xpm » proporcionada.

Asegúrate de que la imagen sea una imagen XPM válida. Los errores se ignoran sin aviso.

Ten en cuenta que es posible reducir ligeramente el tamaño de la variable XPM utilizando una declaración poco habitual:

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

El « const » adicional hace que toda la definición sea de solo lectura, lo cual resulta ligeramente más eficiente (por ejemplo, cuando el código se encuentra en una biblioteca compartida) y permite almacenarla en la ROM junto con la aplicación.

QImage::QImage(const QSize &size, QImage::Format format)

Crea una imagen con los valores proporcionados en « size » y « format ».

Se devuelve una imagen de tipo ` null ` si no se puede asignar memoria.

Advertencia: Esto creará un `QImage` con datos no inicializados. Llama a ` fill()` para rellenar la imagen con un valor de píxel adecuado antes de dibujar en ella con ` QPainter`.

[explicit] QImage::QImage(const QString &fileName, const char *format = nullptr)

Crea una imagen e intenta cargarla desde el archivo con la URL especificada fileName.

El cargador intenta leer la imagen utilizando el formato de imagen especificado ( format). Si no se especifica el formato de imagen ( format ) (que es el valor por defecto), se detecta automáticamente en función de la extensión y el encabezado del archivo. Para más detalles, véase {QImageReader::setAutoDetectImageFormat()}{QImageReader}.

Si la carga de la imagen ha fallado, este objeto es una imagen nula.

El nombre del archivo puede hacer referencia a un archivo real en el disco o a uno de los recursos incrustados de la aplicación. Consulte la descripción general del sistema de recursos para obtener más detalles sobre cómo incrustar imágenes y otros archivos de recursos en el ejecutable de la aplicación.

Véase también isNull() y Reading and Writing Image Files.

QImage::QImage(int width, int height, QImage::Format format)

Crea una imagen con los valores proporcionados en width, height y format.

Se devolverá una imagen de tipo null si no se puede asignar memoria.

Advertencia: Esto creará un QImage con datos no inicializados. Llama a fill() para rellenar la imagen con un valor de píxel adecuado antes de dibujar sobre ella con QPainter.

QImage::QImage(const uchar *data, int width, int height, QImage::Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr)

Crea una imagen con los parámetros ` width`, ` height ` y ` format` especificados, que utiliza un búfer de memoria de solo lectura ya existente, ` data`. Los parámetros ` width ` y ` height ` deben especificarse en píxeles, ` data ` debe estar alineado a 32 bits, y cada línea de exploración de datos de la imagen también debe estar alineada a 32 bits.

El búfer debe permanecer válido durante toda la vida útil del QImage y de todas las copias que no hayan sido modificadas o separadas de alguna otra forma del búfer original. La imagen no elimina el búfer al destruirse. Se puede proporcionar un puntero a una función cleanupFunction junto con un puntero adicional cleanupInfo que se llamará cuando se destruya la última copia.

Si format es un formato de color indexado, la tabla de colores de la imagen estará inicialmente vacía y deberá ampliarse lo suficiente con setColorCount() o setColorTable() antes de utilizar la imagen.

A diferencia del constructor similar de `QImage` que toma un búfer de datos no constante, esta versión nunca modificará el contenido del búfer. Por ejemplo, llamar a ` QImage::bits()` devolverá una copia profunda de la imagen, en lugar del búfer pasado al constructor. Esto permite la eficiencia de construir un `QImage` a partir de datos sin procesar, sin que exista la posibilidad de que dichos datos se modifiquen.

QImage::QImage(uchar *data, int width, int height, QImage::Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr)

Crea una imagen con los parámetros « width », « height » y « format » proporcionados, que utiliza un búfer de memoria existente, « data ». Los parámetros « width » y « height » deben especificarse en píxeles, « data » debe estar alineado a 32 bits, y cada línea de exploración de datos de la imagen también debe estar alineada a 32 bits.

El búfer debe permanecer válido durante toda la vida útil del objeto `QImage` y de todas las copias que no hayan sido modificadas o separadas de alguna otra forma del búfer original. La imagen no elimina el búfer al destruirse. Se puede proporcionar un puntero a una función ` cleanupFunction ` junto con un puntero adicional ` cleanupInfo ` que se llamará cuando se destruya la última copia.

Si format es un formato de color indexado, la tabla de colores de la imagen estará inicialmente vacía y deberá ampliarse lo suficiente con setColorCount() o setColorTable() antes de utilizar la imagen.

QImage::QImage(const uchar *data, int width, int height, qsizetype bytesPerLine, QImage::Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr)

Crea una imagen con los valores proporcionados en « width », « height » y « format », que utiliza un búfer de memoria existente, « data ». Los valores de « width » y « height » deben especificarse en píxeles. « bytesPerLine » especifica el número de bytes por línea (stride).

El búfer debe permanecer válido durante toda la vida útil del QImage y de todas las copias que no hayan sido modificadas ni separadas de alguna otra forma del búfer original. La imagen no elimina el búfer al destruirse. Se puede proporcionar un puntero a una función cleanupFunction junto con un puntero adicional cleanupInfo que se llamará cuando se destruya la última copia.

Si format es un formato de color indexado, la tabla de colores de la imagen está inicialmente vacía y debe ampliarse lo suficiente con setColorCount() o setColorTable() antes de utilizar la imagen.

A diferencia del constructor similar de QImage, que toma un búfer de datos no constante, esta versión nunca modificará el contenido del búfer. Por ejemplo, llamar a ` QImage::bits()` devolverá una copia profunda de la imagen, en lugar del búfer pasado al constructor. Esto permite la eficiencia de construir un QImage a partir de datos sin procesar, sin que exista la posibilidad de que dichos datos se modifiquen.

QImage::QImage(uchar *data, int width, int height, qsizetype bytesPerLine, QImage::Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr)

Crea una imagen con los valores proporcionados en ` width`, ` height ` y ` format`, que utiliza un búfer de memoria existente, ` data`. Los valores de ` width ` y ` height ` deben especificarse en píxeles. ` bytesPerLine ` especifica el número de bytes por línea (stride).

El búfer debe permanecer válido durante toda la vida útil del objeto `QImage` y de todas las copias que no se hayan modificado ni se hayan desvinculado de alguna otra forma del búfer original. La imagen no elimina el búfer al destruirse. Se puede proporcionar un puntero a una función ` cleanupFunction ` junto con un puntero adicional ` cleanupInfo `, que se llamará cuando se destruya la última copia.

Si format es un formato de color indexado, la tabla de colores de la imagen está inicialmente vacía y debe ampliarse lo suficiente con setColorCount() o setColorTable() antes de utilizar la imagen.

QImage::QImage(const QImage &image)

Crea una copia superficial del objeto ` image` indicado.

Para obtener más información sobre las copias superficiales, consulta la documentación sobre el intercambio implícito de datos.

Véase también copy().

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

Crea una instancia de QImage mediante «move», haciendo que apunte al mismo objeto al que apuntaba « other ».

[virtual noexcept] QImage::~QImage()

Destruye la imagen y limpia todo.

bool QImage::allGray() const

Devuelve « true » si todos los colores de la imagen son tonos de gris (es decir, si sus componentes de rojo, verde y azul son iguales); en caso contrario, devuelve «false».

Ten en cuenta que esta función es lenta para imágenes sin tabla de colores.

Véase también isGrayscale().

void QImage::applyColorTransform(const QColorTransform &transform)

Aplica la transformación de color « transform » a todos los píxeles de la imagen.

[since 6.8] void QImage::applyColorTransform(const QColorTransform &transform, QImage::Format toFormat, Qt::ImageConversionFlags flags = Qt::AutoColor)

Aplica la transformación de color transform a todos los píxeles de la imagen y convierte el formato de la imagen a toFormat.

La conversión de imagen especificada flags controla cómo se gestionan los datos de la imagen durante el proceso de conversión de formato.

Esta función se introdujo en Qt 6.8.

int QImage::bitPlaneCount() const

Devuelve el número de planos de bits de la imagen.

El número de planos de bits es el número de bits de información de color y transparencia de cada píxel. Este valor es diferente (es decir, menor) de la profundidad cuando el formato de imagen contiene bits no utilizados.

Véase también depth(), format() y Image Formats.

uchar *QImage::bits()

Devuelve un puntero a los datos del primer píxel. Esto equivale a ` scanLine(0)`.

Ten en cuenta que ` QImage ` utiliza el intercambio implícito de datos. Esta función realiza una copia profunda de los datos de píxeles compartidos, lo que garantiza que este ` QImage ` sea el único que utilice el valor de retorno actual.

Véanse también scanLine(), sizeInBytes() y constBits().

const uchar *QImage::bits() const

Ten en cuenta que ` QImage ` utiliza el intercambio implícito de datos, pero esta función no realiza una copia profunda de los datos de píxeles compartidos, ya que los datos devueltos son de tipo `const`.

Se trata de una función sobrecargada.

qsizetype QImage::bytesPerLine() const

Devuelve el número de bytes por línea de exploración de la imagen.

Esto equivale a sizeInBytes() / height() si height() es distinto de cero.

Véase también scanLine().

qint64 QImage::cacheKey() const

Devuelve un número que identifica el contenido de este objeto ` QImage `. Los distintos objetos ` QImage ` solo pueden tener la misma clave si hacen referencia al mismo contenido.

La clave cambiará cuando se modifique la imagen.

QRgb QImage::color(int i) const

Devuelve el color de la tabla de colores correspondiente al índice i. El primer color se encuentra en el índice 0.

Los colores de la tabla de colores de una imagen se especifican como cuádruples ARGB (QRgb). Utiliza las funciones qAlpha(), qRed(), qGreen() y qBlue() para obtener los componentes del valor del color.

Véase también setColor(), pixelIndex() y Pixel Manipulation.

int QImage::colorCount() const

Devuelve el tamaño de la tabla de colores de la imagen.

Ten en cuenta que colorCount() devuelve 0 para imágenes de 32 bpp, ya que estas imágenes no utilizan tablas de colores, sino que codifican los valores de los píxeles como cuartetos ARGB.

Véase también setColorCount() y Image Information.

QColorSpace QImage::colorSpace() const

Devuelve el espacio de color de la imagen si se ha definido uno.

Véase también ` setColorSpace()`.

QList<QRgb> QImage::colorTable() const

Devuelve una lista con los colores que contiene la tabla de colores de la imagen, o una lista vacía si la imagen no tiene tabla de colores

Véase también setColorTable(), colorCount() y color().

[since 6.4] QImage QImage::colorTransformed(const QColorTransform &transform) const &

Devuelve el color de la imagen transformado mediante transform en todos los píxeles de la imagen.

Nota: Si ` transform ` tiene un espacio de color de origen incompatible con el formato de esta imagen, devuelve un valor nulo ` QImage`. Si ` transform ` tiene un espacio de color de destino incompatible con el formato de esta imagen, la imagen también se convertirá a un formato compatible. Para tener más control sobre la elección del formato de píxel de destino, consulta la sobrecarga de tres argumentos de este método.

Esta función se introdujo en Qt 6.4.

Véase también applyColorTransform().

[since 6.8] QImage QImage::colorTransformed(const QColorTransform &transform, QImage::Format toFormat, Qt::ImageConversionFlags flags = Qt::AutoColor) const &

Devuelve la imagen con los colores transformados mediante « transform » en todos los píxeles de la imagen, devolviendo una imagen con el formato « toFormat ».

La conversión de imagen especificada flags controla cómo se gestionan los datos de la imagen durante el proceso de conversión de formato.

Nota: Si transform tiene un espacio de color de origen incompatible con el formato de esta imagen, o un espacio de color de destino incompatible con toFormat, devuelve un QImage nulo.

Esta función se introdujo en Qt 6.8.

Véase también applyColorTransform().

[since 6.4] QImage QImage::colorTransformed(const QColorTransform &transform) &&

Devuelve el color de la imagen transformado mediante « transform » en todos los píxeles de la imagen.

Esta es una función sobrecargada.

Esta función se introdujo en Qt 6.4.

Véase también ` applyColorTransform()`.

[since 6.8] QImage QImage::colorTransformed(const QColorTransform &transform, QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) &&

Devuelve el color de la imagen transformado mediante « transform » en todos los píxeles de la imagen.

Esta es una función sobrecargada.

Esta función se introdujo en Qt 6.8.

Véase también ` applyColorTransform()`.

const uchar *QImage::constBits() const

Devuelve un puntero a los datos del primer píxel.

Ten en cuenta que QImage utiliza el intercambio implícito de datos, pero esta función no realiza una copia profunda de los datos de píxeles compartidos, ya que los datos devueltos son const.

Véanse también ` bits()` y ` constScanLine()`.

const uchar *QImage::constScanLine(int i) const

Devuelve un puntero a los datos de píxeles de la línea de exploración con índice i. La primera línea de exploración tiene el índice 0.

Los datos de la línea de exploración están alineados, como mínimo, a 32 bits. En el caso de los formatos de 64 bits, siguen la alineación nativa de los enteros de 64 bits (64 bits en la mayoría de las plataformas, pero cabe destacar que son de 32 bits en i386).

Ten en cuenta que QImage utiliza el intercambio implícito de datos, pero esta función no realiza una copia profunda de los datos de píxeles compartidos, ya que los datos devueltos son const.

Véanse también scanLine() y constBits().

void QImage::convertTo(QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor)

Convierte la imagen al formato format especificado sin modificar la imagen original, separándola si es necesario.

Los parámetros de conversión de imagen especificados flags controlan cómo se gestionan los datos de la imagen durante el proceso de conversión.

Véase también convertedTo().

void QImage::convertToColorSpace(const QColorSpace &colorSpace)

Convierte la imagen a un espacio de color « colorSpace ».

Si la imagen no tiene un espacio de color válido, el método no realiza ninguna acción.

Nota: Si colorSpace no es compatible con el formato actual, la imagen se convertirá a uno que sí lo sea.

Véanse también convertedToColorSpace() y setColorSpace().

[since 6.8] void QImage::convertToColorSpace(const QColorSpace &colorSpace, QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor)

Convierte la imagen a colorSpace y format.

Si la imagen no tiene un espacio de color válido, el método no realiza ninguna acción, ni tampoco lo hace si el espacio de color no es compatible con el formato.

La conversión de imagen especificada flags controla cómo se gestionan los datos de la imagen durante el proceso de conversión de formato.

Esta función se introdujo en Qt 6.8.

Véase también convertedToColorSpace() y setColorSpace().

QImage QImage::convertToFormat(QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) &&

QImage QImage::convertToFormat(QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) const &

Devuelve una copia de la imagen en el format especificado.

Los parámetros de conversión de imagen especificados ( flags ) determinan cómo se gestionan los datos de la imagen durante el proceso de conversión.

Véase también convertTo() y Image Formats.

QImage QImage::convertToFormat(QImage::Format format, const QList<QRgb> &colorTable, Qt::ImageConversionFlags flags = Qt::AutoColor) const

Devuelve una copia de la imagen convertida al formato « format » indicado, utilizando el « colorTable » especificado.

La conversión de formatos RGB a formatos indexados es una operación lenta y utilizará un método sencillo basado en el color más cercano, sin difuminado.

Esta es una función sobrecargada.

[since 6.0] QImage QImage::convertedTo(QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) &&

[since 6.0] QImage QImage::convertedTo(QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) const &

Devuelve una copia de la imagen en el format especificado.

Los parámetros de conversión de imágenes especificados flags determinan cómo se gestionan los datos de la imagen durante el proceso de conversión.

Estas funciones se introdujeron en Qt 6.0.

Véase también ` convertTo()` y ` Image Formats`.

QImage QImage::convertedToColorSpace(const QColorSpace &colorSpace) const

Devuelve la imagen convertida a colorSpace.

Si la imagen no tiene un espacio de color válido, se devuelve un ` QImage ` nulo.

Nota: Si colorSpace no es compatible con el formato actual, la imagen devuelta también se convertirá a un formato que sí lo sea. Para tener un mayor control sobre el formato de la imagen devuelta, consulta la sobrecarga de tres argumentos de este método.

Véase también ` convertToColorSpace()` y ` colorTransformed()`.

[since 6.8] QImage QImage::convertedToColorSpace(const QColorSpace &colorSpace, QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) &&

[since 6.8] QImage QImage::convertedToColorSpace(const QColorSpace &colorSpace, QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) const &

Devuelve la imagen convertida a colorSpace y format.

Si la imagen no tiene un espacio de color válido, se devuelve un valor nulo para « QImage ».

Los parámetros de conversión de imagen especificados ( flags ) controlan cómo se gestionan los datos de la imagen durante el proceso de conversión de formato.

Estas funciones se introdujeron en Qt 6.8.

Véase también colorTransformed().

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

Devuelve una subárea de la imagen como una nueva imagen.

La imagen devuelta se copia desde la posición (rectangle.x(), rectangle.y()) de esta imagen y siempre tendrá el tamaño indicado en rectangle.

En las áreas que se encuentran fuera de esta imagen, los píxeles se establecen en 0. Para imágenes RGB de 32 bits, esto significa negro; para imágenes ARGB de 32 bits, significa negro transparente; para imágenes de 8 bits, significa el color con índice 0 en la tabla de colores, que puede ser cualquiera; para imágenes de 1 bit, significa Qt::color0.

Si el rectángulo dado rectangle es un rectángulo nulo, se copia la imagen completa.

Véase también ` QImage()`.

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

La imagen devuelta se copia a partir de las coordenadas (x, y) de esta imagen, y siempre tendrá los valores width y height especificados. En las zonas que quedan fuera de esta imagen, los píxeles se establecen en 0.

Esta es una función sobrecargada.

QImage QImage::createAlphaMask(Qt::ImageConversionFlags flags = Qt::AutoColor) const

Crea y devuelve una máscara de 1 bpp a partir del búfer alfa de esta imagen. Devuelve una imagen nula si el formato de la imagen es « QImage::Format_RGB32 ».

El argumento ` flags ` es una operación OR bit a bit de ` Qt::ImageConversionFlags` y controla el proceso de conversión. Si se pasa 0 como valor para `flags`, se establecen todas las opciones predeterminadas.

La imagen devuelta tiene un orden de bits «little-endian» (es decir, el formato de la imagen es « QImage::Format_MonoLSB »), que se puede convertir a «big-endian» («QImage::Format_Mono ») utilizando la función « convertToFormat()».

Véanse también createHeuristicMask() y Image Transformations.

QImage QImage::createHeuristicMask(bool clipTight = true) const

Crea y devuelve una máscara heurística de 1 bpp para esta imagen.

La función funciona seleccionando un color de una de las esquinas y, a continuación, eliminando píxeles de ese color empezando por todos los bordes. Las cuatro esquinas determinan qué color se va a enmascarar. En caso de empate (lo que generalmente significa que esta función no es aplicable a la imagen), el resultado es arbitrario.

La imagen devuelta tiene orden de bits «little-endian» (es decir, el formato de la imagen es QImage::Format_MonoLSB), que se puede convertir a «big-endian» (QImage::Format_Mono) utilizando la función convertToFormat().

Si clipTight es verdadero (valor por defecto), la máscara tiene el tamaño justo para cubrir los píxeles; en caso contrario, la máscara es más grande que los píxeles de datos.

Ten en cuenta que esta función ignora el búfer alfa.

Véanse también createAlphaMask() y Image Transformations.

QImage QImage::createMaskFromColor(QRgb color, Qt::MaskMode mode = Qt::MaskInColor) const

Crea y devuelve una máscara para esta imagen basándose en el valor de « color » proporcionado. Si el valor de « mode » es «MaskInColor» (el valor por defecto), todos los píxeles que coincidan con « color » serán píxeles opacos en la máscara. Si « mode » es «MaskOutColor», todos los píxeles que coincidan con el color indicado serán transparentes.

Véase también createAlphaMask() y createHeuristicMask().

int QImage::depth() const

Devuelve la profundidad de la imagen.

La profundidad de la imagen es el número de bits que se utilizan para almacenar un único píxel, lo que también se denomina «bits por píxel» (bpp).

Las profundidades admitidas son 1, 8, 16, 24, 32 y 64.

Véase también bitPlaneCount(), convertToFormat(), Image Formats y Image Information.

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

Devuelve el tamaño de la imagen en píxeles independientes del dispositivo.

Este valor debe utilizarse cuando se emplee el tamaño de la imagen en cálculos de tamaño de la interfaz de usuario.

El valor devuelto es equivalente a image.size() / image.devicePixelRatio().

Esta función se introdujo en Qt 6.2.

qreal QImage::devicePixelRatio() const

Devuelve la relación de píxeles del dispositivo para la imagen. Se trata de la relación entre los píxeles del dispositivo y los píxeles independientes del dispositivo.

Utiliza esta función al calcular la geometría del diseño en función del tamaño de la imagen: ` QSize layoutSize = image.size() / image.devicePixelRatio()`

El valor por defecto es 1,0.

Véanse también ` setDevicePixelRatio()` y ` QImageReader`.

int QImage::dotsPerMeterX() const

Devuelve el número de píxeles que caben horizontalmente en un metro físico. Junto con la función dotsPerMeterY(), este número define la escala y la relación de aspecto previstas para la imagen.

Véase también setDotsPerMeterX() y Image Information.

int QImage::dotsPerMeterY() const

Devuelve el número de píxeles que caben verticalmente en un metro físico. Junto con la función dotsPerMeterX(), este número define la escala y la relación de aspecto previstas para la imagen.

Véase también setDotsPerMeterY() y Image Information.

void QImage::fill(uint pixelValue)

Rellena toda la imagen con el valor dado en « pixelValue ».

Si la profundidad de esta imagen es 1, solo se utiliza el bit menos significativo. Si se indica fill(0), fill(2), etc., la imagen se rellena con ceros. Si se especifica fill(1), fill(3), etc., la imagen se rellena con unos. Si la profundidad es 8, se utilizan los 8 bits menos significativos, y si la profundidad es 16, se utilizan los 16 bits menos significativos.

Si la profundidad de la imagen es superior a 32 bits, el resultado es indefinido.

Nota: No hay ningún método de lectura correspondiente, aunque ` QImage::pixelIndex()` devolverá el mismo valor para los formatos indexados, y ` QImage::pixel()` para los formatos RGB32, ARGB32 y ARGB32PM.

Véase también depth() y Image Transformations.

void QImage::fill(Qt::GlobalColor color)

Rellena la imagen con el valor dado color, descrito como un color global estándar.

Esta es una función sobrecargada.

void QImage::fill(const QColor &color)

Rellena toda la imagen con el valor proporcionado en « color ».

Si la profundidad de la imagen es 1, la imagen se rellenará con un 1 si color es igual a Qt::color1; en caso contrario, se rellenará con un 0.

Si la profundidad de la imagen es 8, la imagen se rellenará con el índice correspondiente a color en la tabla de colores, si existe; en caso contrario, se rellenará con 0.

Esta es una función sobrecargada.

[since 6.9] void QImage::flip(Qt::Orientations orient = Qt::Vertical)

Voltea o refleja la imagen en dirección horizontal y/o vertical, dependiendo de ` orient`.

Esta función se introdujo en Qt 6.9.

Véase también flipped(Qt::Orientations) y Image Transformations.

[since 6.9] QImage QImage::flipped(Qt::Orientations orient = Qt::Vertical) &&

[since 6.9] QImage QImage::flipped(Qt::Orientations orient = Qt::Vertical) const &

Devuelve una versión invertida o reflejada de la imagen, reflejada en horizontal y/o en vertical, dependiendo del valor de ` orient`.

Ten en cuenta que la imagen original no se modifica.

Estas funciones se introdujeron en Qt 6.9.

Véase también flip(Qt::Orientations) y Image Transformations.

QImage::Format QImage::format() const

Devuelve el formato de la imagen.

Véase también Image Formats.

[static, since 6.2] QImage QImage::fromData(QByteArrayView data, const char *format = nullptr)

Crea una imagen a partir de los datos proporcionados en QByteArrayView data . El cargador intenta leer la imagen utilizando el format especificado. Si no se especifica format (que es el valor por defecto), el cargador analiza los datos en busca de una cabecera para determinar el formato del archivo.

Si se especifica format, debe ser uno de los valores devueltos por QImageReader::supportedImageFormats().

Si falla la carga de la imagen, la imagen devuelta será una imagen nula.

Esta función se introdujo en Qt 6.2.

Véase también load(), save() y Reading and Writing Image Files.

[static] QImage QImage::fromData(const QByteArray &data, const char *format = nullptr)

Crea un objeto ` QImage ` a partir del objeto ` QByteArray ` ` data` proporcionado.

Esta es una función sobrecargada.

[static] QImage QImage::fromData(const uchar *data, int size, const char *format = nullptr)

Crea un objeto ` QImage ` a partir de los primeros ` size ` bytes del archivo binario ` data` proporcionado.

Esta es una función sobrecargada.

[static, since 6.0] QImage QImage::fromHBITMAP(HBITMAP hbitmap)

Devuelve un objeto ` QImage ` equivalente al objeto ` hbitmap` proporcionado.

HBITMAP no almacena información sobre el canal alfa.

En el caso habitual, el canal alfa se ignora y se crea una imagen totalmente opaca (normalmente con el formato « QImage::Format_RGB32 »).

Sin embargo, hay casos en los que se utiliza el canal alfa, por ejemplo, para el icono de la aplicación o los iconos de la bandeja del sistema. En ese caso, se debe llamar a ` reinterpretAsFormat(QImage::Format_ARGB32) ` sobre la imagen devuelta para garantizar que el formato sea correcto.

Esta función se introdujo en Qt 6.0.

Véanse también toHBITMAP() y reinterpretAsFormat().

[static, since 6.0] QImage QImage::fromHICON(HICON icon)

Devuelve un objeto ` QImage ` equivalente al ` icon` indicado.

Esta función se introdujo en Qt 6.0.

Véase también toHICON().

bool QImage::hasAlphaChannel() const

Devuelve « true » si la imagen tiene un formato que respeta el canal alfa; en caso contrario, devuelve « false ».

Véase también Image Information.

int QImage::height() const

Devuelve la altura de la imagen.

Véase también Image Information.

void QImage::invertPixels(QImage::InvertMode mode = InvertRgb)

Invierte todos los valores de píxeles de la imagen.

El valor de inversión indicado mode solo tiene sentido cuando la profundidad de la imagen es 32. El valor por defecto mode es InvertRgb, lo que deja el canal alfa sin cambios. Si el valor mode es InvertRgba, los bits alfa también se invierten.

Invertir una imagen de 8 bits significa sustituir todos los píxeles que utilizan el índice de color i por un píxel que utilice el índice de color 255 menos i. Lo mismo ocurre con una imagen de 1 bit. Ten en cuenta que la tabla de colores no se modifica.

Si la imagen tiene un canal alfa premultiplicado, primero se convierte a un formato de imagen no premultiplicado para poder invertirla y, a continuación, se vuelve a convertir.

Véase también « Image Transformations ».

bool QImage::isGrayscale() const

En el caso de las imágenes de 32 bits, esta función es equivalente a ` allGray()`.

Para imágenes con tabla de colores, esta función devuelve ` true ` si `color(i)` es ` QRgb(i, i, i)` para todos los índices de la tabla de colores; en caso contrario, devuelve ` false`.

Véase también allGray() y Image Formats.

bool QImage::isNull() const

Devuelve « true » si se trata de una imagen nula; en caso contrario, devuelve « false ».

Una imagen nula tiene todos los parámetros establecidos en cero y no tiene datos asignados.

bool QImage::load(const QString &fileName, const char *format = nullptr)

Carga una imagen desde el archivo con el « fileName » indicado. Devuelve « true » si la imagen se ha cargado correctamente; en caso contrario, invalida la imagen y devuelve « false ».

El cargador intenta leer la imagen utilizando el formato format especificado, por ejemplo, PNG o JPG. Si no se especifica format (que es el valor por defecto), se detecta automáticamente en función de la extensión y el encabezado del archivo. Para más detalles, véase QImageReader::setAutoDetectImageFormat().

El nombre del archivo puede hacer referencia a un archivo real en el disco o a uno de los recursos incrustados de la aplicación. Consulte la descripción general del sistema de recursos para obtener más detalles sobre cómo incrustar imágenes y otros archivos de recursos en el ejecutable de la aplicación.

Véase también Reading and Writing Image Files.

bool QImage::load(QIODevice *device, const char *format)

Esta función lee un objeto « QImage » desde la dirección « device » indicada. Esto puede utilizarse, por ejemplo, para cargar una imagen directamente en un objeto « QByteArray ».

Se trata de una función sobrecargada.

[since 6.2] bool QImage::loadFromData(QByteArrayView data, const char *format = nullptr)

Carga una imagen a partir de la extensión de formato de imagen ( QByteArrayView ) indicada data. Devuelve « true » si la imagen se ha cargado correctamente; en caso contrario, invalida la imagen y devuelve « false ».

El cargador intenta leer la imagen utilizando el formato especificado format, por ejemplo, PNG o JPG. Si no se especifica format (que es el valor por defecto), el cargador busca en el archivo una cabecera para adivinar el formato del archivo.

Esta función se introdujo en Qt 6.2.

Véase también « Reading and Writing Image Files ».

bool QImage::loadFromData(const QByteArray &data, const char *format = nullptr)

Carga una imagen desde la dirección QByteArray data .

Esta es una función sobrecargada.

bool QImage::loadFromData(const uchar *data, int len, const char *format = nullptr)

Carga una imagen a partir de los primeros len bytes del archivo binario data.

Esta es una función sobrecargada.

[since 6.0, until 6.13] void QImage::mirror(bool horizontal = false, bool vertical = true)

Está previsto que esta función quede obsoleta en la versión 6.13.

Utiliza en su lugar flip(Qt::Orientations).

Invertirá la imagen en dirección horizontal y/o vertical, dependiendo de si horizontal y vertical están establecidos en true o false.

Esta función se introdujo en Qt 6.0.

Véase también mirrored() y Image Transformations.

[until 6.13] QImage QImage::mirrored(bool horizontal = false, bool vertical = true) &&

[until 6.13] QImage QImage::mirrored(bool horizontal = false, bool vertical = true) const &

Está previsto que esta función quede obsoleta en la versión 6.13.

Utiliza en su lugar flipped(Qt::Orientations).

Devuelve una imagen especular, reflejada en horizontal y/o en vertical, dependiendo de si horizontal y vertical están establecidos en true o false.

Ten en cuenta que la imagen original no se modifica.

Véase también mirror() y Image Transformations.

QPoint QImage::offset() const

Devuelve el número de píxeles en el que se pretende desplazar la imagen al posicionarla en relación con otras imágenes.

Véase también setOffset() y Image Information.

QRgb QImage::pixel(const QPoint &position) const

Devuelve el color del píxel situado en la posición indicada position.

Si la coordenada « position » no es válida, los resultados son indefinidos.

Advertencia: Esta función consume muchos recursos cuando se utiliza para manipulaciones masivas de píxeles. Utiliza constBits() o constScanLine() cuando sea necesario leer muchos píxeles.

Véase también setPixel(), valid(), constBits(), constScanLine() y Pixel Manipulation.

QRgb QImage::pixel(int x, int y) const

Devuelve el color del píxel situado en las coordenadas (x, y).

Esta es una función sobrecargada.

QColor QImage::pixelColor(const QPoint &position) const

Devuelve el color del píxel situado en la coordenada dada ` position ` como un objeto ` QColor`.

Si la coordenada « position » no es válida, se devuelve un valor « QColor » no válido.

Advertencia: Esta función consume muchos recursos cuando se utiliza para manipulaciones masivas de píxeles. Utiliza constBits() o constScanLine() cuando sea necesario leer muchos píxeles.

Véase también setPixelColor(), setPixel(), valid(), constBits(), constScanLine() y Pixel Manipulation.

QColor QImage::pixelColor(int x, int y) const

Devuelve el color del píxel situado en las coordenadas (x, y) como un objeto de tipo « QColor ».

Esta es una función sobrecargada.

[noexcept] QPixelFormat QImage::pixelFormat() const

Devuelve el objeto « QImage::Format » como un QPixelFormat

int QImage::pixelIndex(const QPoint &position) const

Devuelve el índice del píxel en la imagen especificada position.

Si position no es válido, o si la imagen no es una imagen con paleta (depth() > 8), los resultados son indefinidos.

Véase también ` valid()`, ` depth()` y ` Pixel Manipulation`.

int QImage::pixelIndex(int x, int y) const

Devuelve el índice del píxel en (x, y).

Esta es una función sobrecargada.

QRect QImage::rect() const

Devuelve el rectángulo envolvente (0, 0, width(), height()) de la imagen.

Véase también Image Information.

bool QImage::reinterpretAsFormat(QImage::Format format)

Cambia el formato de la imagen a format sin modificar los datos. Solo funciona entre formatos de la misma profundidad.

Devuelve « true » si se realiza correctamente.

Esta función se puede utilizar para convertir imágenes con canales alfa a sus formatos opacos correspondientes si se sabe que los datos son exclusivamente opacos, o para cambiar el formato de un búfer de imagen determinado antes de sobrescribirlo con nuevos datos.

Advertencia: La función no comprueba si los datos de la imagen son válidos en el nuevo formato y seguirá devolviendo ` true ` si las profundidades son compatibles. Las operaciones sobre una imagen con datos no válidos tienen un comportamiento indefinido.

Advertencia: Si la imagen no está desvinculada, esto provocará que se copien los datos.

Véase también ` hasAlphaChannel()` y ` convertToFormat()`.

[since 6.0] void QImage::rgbSwap()

Intercambia los valores de los componentes rojo y azul de todos los píxeles, lo que equivale a convertir una imagen RGB en una imagen BGR.

Esta función se introdujo en Qt 6.0.

Véase también rgbSwapped() y Image Transformations.

QImage QImage::rgbSwapped() &&

QImage QImage::rgbSwapped() const &

Devuelve un objeto ` QImage ` en el que se han intercambiado los valores de los componentes rojo y azul de todos los píxeles, lo que equivale a convertir una imagen RGB en una imagen BGR.

El ` QImage ` original no se modifica.

Véase también ` rgbSwap()` y ` Image Transformations`.

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

Guarda la imagen en el archivo con el nombre « fileName » especificado, utilizando el archivo de imagen « format » y el factor « quality » indicados. Si « format » es « nullptr », « QImage » intentará adivinar el formato fijándose en la extensión de « fileName ».

El factor quality debe estar comprendido entre 0 y 100 o ser -1. Especifica 0 para obtener archivos comprimidos pequeños, 100 para archivos sin comprimir grandes y -1 (el valor por defecto) para utilizar la configuración predeterminada.

Devuelve ` true ` si la imagen se ha guardado correctamente; en caso contrario, devuelve ` false`.

Véase también Reading and Writing Image Files.

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

Esta función escribe un archivo « QImage » en la ruta indicada « device ».

Esto se puede utilizar, por ejemplo, para guardar una imagen directamente en un archivo ` QByteArray`:

QImage image;
QByteArray ba;
QBuffer buffer(&ba);
buffer.open(QIODevice::WriteOnly);
image.save(&buffer, "PNG"); // writes image into ba in PNG format

Se trata de una función sobrecargada.

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

Devuelve una copia de la imagen escalada a un rectángulo definido por el « size » proporcionado, de acuerdo con los parámetros « aspectRatioMode » y « transformMode » indicados.

Ilustración que muestra tres formas diferentes de redimensionar imágenes con el modo de relación de aspecto

  • Si aspectRatioMode es Qt::IgnoreAspectRatio, la imagen se escala a size.
  • Si aspectRatioMode es Qt::KeepAspectRatio, la imagen se escala a un rectángulo tan grande como sea posible dentro de size, conservando la relación de aspecto.
  • Si aspectRatioMode es Qt::KeepAspectRatioByExpanding, la imagen se escala a un rectángulo lo más pequeño posible fuera de size, conservando la relación de aspecto.

Si el parámetro size está vacío, esta función devuelve una imagen nula.

Véase también isNull() y Image Transformations.

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

Devuelve una copia de la imagen escalada a un rectángulo con los valores de « width » y « height » especificados, de acuerdo con los valores de « aspectRatioMode » y « transformMode » indicados.

Si el valor de width o el de height es cero o negativo, esta función devuelve una imagen nula.

Esta es una función sobrecargada.

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

Devuelve una copia escalada de la imagen. La imagen devuelta se escala a la resolución especificada height utilizando la transformación indicada mode.

Esta función calcula automáticamente el ancho de la imagen para que se mantenga la relación de aspecto de la misma.

Si el valor de height es 0 o negativo, se devuelve una imagen nula.

Véase también Image Transformations.

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

Devuelve una copia escalada de la imagen. La imagen devuelta se escala al width indicado utilizando la transformación especificada mode.

Esta función calcula automáticamente la altura de la imagen para que se mantenga su relación de aspecto.

Si el width dado es 0 o negativo, se devuelve una imagen nula.

Véase también Image Transformations.

uchar *QImage::scanLine(int i)

Devuelve un puntero a los datos de píxeles de la línea de exploración con índice i. La primera línea de exploración tiene índice 0.

Los datos de la línea de exploración están alineados, como mínimo, a 32 bits. En el caso de los formatos de 64 bits, siguen la alineación nativa de los enteros de 64 bits (64 bits en la mayoría de las plataformas, pero cabe destacar que son de 32 bits en i386).

Por ejemplo, para eliminar el componente verde de cada píxel de una imagen:

for (int y = 0; y < image.height(); ++y) {
    QRgb *line = reinterpret_cast<QRgb*>(image.scanLine(y));
    for (int x = 0; x < image.width(); ++x) {
        QRgb &rgb = line[x];
        rgb = qRgba(qRed(rgb), qGreen(0), qBlue(rgb), qAlpha(rgb));
    }
}

Advertencia: Si estás accediendo a datos de imagen de 32 bpp, convierte el puntero devuelto a QRgb* (QRgb tiene un tamaño de 32 bits) y utilízalo para leer o escribir el valor del píxel. No se puede utilizar directamente el puntero uchar*, ya que el formato de los píxeles depende del orden de los bytes en la plataforma subyacente. Utiliza qRed(), qGreen(), qBlue() y qAlpha() para acceder a los píxeles.

Véase también bytesPerLine(), bits(), Pixel Manipulation y constScanLine().

const uchar *QImage::scanLine(int i) const

Esta es una función sobrecargada.

void QImage::setAlphaChannel(const QImage &alphaChannel)

Establece el canal alfa de esta imagen según el valor proporcionado en alphaChannel.

Si alphaChannel es una imagen alfa de 8 bits, se utilizan directamente los valores alfa. En caso contrario, alphaChannel se convierte a escala de grises de 8 bits y se utiliza la intensidad de los valores de los píxeles.

Si la imagen ya tiene un canal alfa, el canal alfa existente se multiplica por el nuevo. Si la imagen no tiene canal alfa, se convertirá a un formato que sí lo tenga.

La operación es similar a pintar alphaChannel como una imagen alfa sobre esta imagen utilizando QPainter::CompositionMode_DestinationIn.

Véanse también hasAlphaChannel(), Image Transformations y Image Formats.

void QImage::setColor(int index, QRgb colorValue)

Establece el color en la posición indicada index de la tabla de colores con el valor especificado colorValue. El valor del color es un cuádruplet ARGB.

Si index se encuentra fuera del tamaño actual de la tabla de colores, esta se amplía con setColorCount().

Véase también color(), colorCount(), setColorTable() y Pixel Manipulation.

void QImage::setColorCount(int colorCount)

Cambia el tamaño de la tabla de colores para que contenga colorCount entradas.

Si se amplía la tabla de colores, todos los colores adicionales se establecerán como transparentes (es decir, qRgba(0, 0, 0, 0)).

Cuando se utilice la imagen, la tabla de colores deberá ser lo suficientemente grande como para contener entradas para todos los valores de píxel/índice presentes en la imagen; de lo contrario, los resultados serán indefinidos.

Véase también colorCount(), colorTable(), setColor() y Image Transformations.

void QImage::setColorSpace(const QColorSpace &colorSpace)

Establece el espacio de color de la imagen en « colorSpace » sin realizar ninguna conversión en los datos de la imagen.

Véase también ` colorSpace()`.

void QImage::setColorTable(const QList<QRgb> &colors)

Establece la tabla de colores utilizada para convertir los índices de color en valores « QRgb », según lo especificado en colors.

Cuando se utiliza la imagen, la tabla de colores debe ser lo suficientemente grande como para contener entradas para todos los valores de píxel/índice presentes en la imagen; de lo contrario, los resultados son indefinidos.

Véase también colorTable(), setColor() y Image Transformations.

void QImage::setDevicePixelRatio(qreal scaleFactor)

Establece la relación de píxeles del dispositivo para la imagen. Se trata de la relación entre los píxeles de la imagen y los píxeles independientes del dispositivo.

El valor predeterminado de « scaleFactor » es 1,0. Establecerlo en otro valor tiene dos efectos:

Los QPainters que se abran sobre la imagen se escalarán. Por ejemplo, pintar sobre una imagen de 200x200 con una relación de 2,0 dará como resultado unos límites de pintura efectivos (independientes del dispositivo) de 100x100.

Las rutas de código en Qt que calculan la geometría del diseño en función del tamaño de la imagen tendrán en cuenta esta relación: QSize layoutSize = image.size() / image.devicePixelRatio() El efecto final de esto es que la imagen se muestra como una imagen de alta resolución (DPI) en lugar de como una imagen de gran tamaño (véase Drawing High Resolution Versions of Pixmaps and Images).

Véanse también devicePixelRatio() y deviceIndependentSize().

void QImage::setDotsPerMeterX(int x)

Establece el número de píxeles que caben horizontalmente en un metro físico, en x.

Junto con dotsPerMeterY(), este número define la escala y la relación de aspecto previstas para la imagen, y determina la escala a la que QPainter dibujará los gráficos en la imagen. No modifica la escala ni la relación de aspecto de la imagen cuando se representa en otros dispositivos de pintura.

Véase también dotsPerMeterX() y Image Information.

void QImage::setDotsPerMeterY(int y)

Establece el número de píxeles que caben verticalmente en un metro físico, en y.

Junto con dotsPerMeterX(), este número define la escala y la relación de aspecto previstas de la imagen, y determina la escala a la que QPainter dibujará los gráficos en la imagen. No modifica la escala ni la relación de aspecto de la imagen cuando se representa en otros dispositivos de pintura.

Véase también dotsPerMeterY() y Image Information.

void QImage::setOffset(const QPoint &offset)

Establece el número de píxeles en el que se desea desplazar la imagen al posicionarla en relación con otras imágenes, en offset.

Véase también offset() y Image Information.

void QImage::setPixel(const QPoint &position, uint index_or_rgb)

Establece el índice de píxel o el color en la posición indicada por ` position ` en ` index_or_rgb`.

Si el formato de la imagen es monocromo o con paleta, el valor de « index_or_rgb » debe ser un índice de la tabla de colores de la imagen; en caso contrario, el parámetro debe ser un valor de « QRgb ».

Si position no es un par de coordenadas válido en la imagen, o si index_or_rgb >= colorCount() en el caso de imágenes monocromáticas y con paleta, el resultado es indefinido.

Advertencia: Esta función consume muchos recursos debido a la llamada a la función interna detach() que se invoca en su interior; si el rendimiento es un factor importante, recomendamos utilizar scanLine() o bits() para acceder directamente a los datos de los píxeles.

Véase también pixel() y Pixel Manipulation.

void QImage::setPixel(int x, int y, uint index_or_rgb)

Establece el índice de píxel o el color en (x, y) como index_or_rgb.

Esta es una función sobrecargada.

void QImage::setPixelColor(const QPoint &position, const QColor &color)

Establece el color en la posición indicada position como color.

Si « position » no es un par de coordenadas válido en la imagen, o si el formato de la imagen es monocromo o con paleta, el resultado es indefinido.

Advertencia: Esta función consume muchos recursos debido a la llamada a la función interna detach() que se invoca en su interior; si el rendimiento es un factor importante, recomendamos utilizar scanLine() o bits() para acceder directamente a los datos de los píxeles.

Véase también pixelColor(), pixel(), bits(), scanLine() y Pixel Manipulation.

void QImage::setPixelColor(int x, int y, const QColor &color)

Establece el color del píxel situado en (x, y) en color.

Esta es una función sobrecargada.

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

Establece el texto de la imagen en el valor proporcionado text y lo asocia al valor proporcionado key.

Si solo quieres almacenar un único bloque de texto (es decir, un «comentario» o simplemente una descripción), puedes pasar una clave vacía o utilizar una clave genérica como «Description».

El texto de la imagen se incrusta en los datos de la imagen al llamar a save() o QImageWriter::write().

No todos los formatos de imagen admiten texto incrustado. Puedes averiguar si una imagen o un formato concreto admite la incrustación de texto utilizando QImageWriter::supportsOption(). A continuación te ofrecemos un ejemplo:

    QImageWriter writer;
    writer.setFormat("png");
    if (writer.supportsOption(QImageIOHandler::Description))
        qDebug() << "Png supports embedded text";

Puedes utilizar QImageWriter::supportedImageFormats() para averiguar qué formatos de imagen tienes disponibles.

Véase también text() y textKeys().

QSize QImage::size() const

Devuelve el tamaño de la imagen, es decir, sus propiedades « width()» y « height()».

Véanse también Image Information y deviceIndependentSize().

qsizetype QImage::sizeInBytes() const

Devuelve el tamaño de los datos de la imagen en bytes.

Véase también bytesPerLine(), bits() y Image Information.

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

Cambia esta imagen por other. Esta operación es muy rápida y nunca falla.

QString QImage::text(const QString &key = QString()) const

Devuelve el texto de la imagen asociado al « key » indicado. Si el « key » especificado es una cadena vacía, se devuelve todo el texto de la imagen, con cada par clave-texto separado por un salto de línea.

Véase también setText() y textKeys().

QStringList QImage::textKeys() const

Devuelve las claves de texto de esta imagen.

Puedes utilizar estas claves con text() para mostrar el texto de la imagen correspondiente a una clave determinada.

Véase también text().

CGImageRef QImage::toCGImage() const

Crea un objeto ` CGImage ` equivalente a este ` QImage` y devuelve un identificador ` CGImageRef `.

El objeto `CGImageRef` devuelto participa en el uso compartido implícito de ` QImage ` y contiene una referencia a los datos de ` QImage `. `CGImage` es inmutable y nunca separará el ` QImage`. Al escribir en el ` QImage `, este se separará como de costumbre.

Esta función es rápida y no copia ni convierte los datos de la imagen.

Si el formato de la imagen no se puede convertir, se devolverá un CGImageRef nulo. Los usuarios de esta función pueden entonces convertir primero el QImage a un formato compatible, por ejemplo, Format_ARGB32_Premultiplied.

Si la imagen no tiene definido un espacio de color, el espacio de color del CGImageRef resultante se establecerá en el espacio de color sRGB.

[since 6.0] HBITMAP QImage::toHBITMAP() const

Crea un equivalente en HBITMAP de QImage.

Devuelve el identificador de HBITMAP.

Es responsabilidad del autor de la llamada liberar los datos de ` HBITMAP ` tras su uso.

Para su uso con llamadas GDI estándar, como ` BitBlt()`, la imagen debe tener el formato ` QImage::Format_RGB32`.

Al utilizar el HBITMAP resultante para la función GDI ` AlphaBlend() `, la imagen debe tener el formato ` QImage::Format_ARGB32_Premultiplied ` (utilice ` convertToFormat()`).

Al utilizar el HBITMAP resultante como icono de la aplicación o como icono de la bandeja del sistema, la imagen debe tener el formato QImage::Format_ARGB32.

Esta función se introdujo en Qt 6.0.

Véase también fromHBITMAP() y convertToFormat().

[since 6.0] HICON QImage::toHICON(const QImage &mask = {}) const

Crea un equivalente en « HICON » de QPixmap, aplicando la máscara mask.

Si mask no es nulo, debe tener el formato QImage::Format_Mono. Devuelve el identificador de HICON.

Es responsabilidad del llamante liberar los datos de HICON tras su uso.

Esta función se introdujo en Qt 6.0.

Véase también fromHICON().

[static noexcept] QImage::Format QImage::toImageFormat(QPixelFormat format)

Convierte « format » en un QImage::Format

[static noexcept] QPixelFormat QImage::toPixelFormat(QImage::Format format)

Convierte « format » en un QPixelFormat

QImage QImage::transformed(const QTransform &matrix, Qt::TransformationMode mode = Qt::FastTransformation) const

Devuelve una copia de la imagen transformada mediante la transformación especificada en matrix y la transformación mode.

La imagen devuelta tendrá normalmente el mismo {Formatos de imagen}{formato} que la imagen original. Sin embargo, una transformación compleja puede dar lugar a una imagen en la que no todos los píxeles estén cubiertos por los píxeles transformados de la imagen original. En tales casos, a esos píxeles de fondo se les asignará un valor de color transparente, y a la imagen transformada se le asignará un formato con canal alfa, incluso si la imagen original no lo tenía.

La transformación matrix se ajusta internamente para compensar cualquier traslación no deseada; es decir, la imagen resultante es la imagen más pequeña que contiene todos los puntos transformados de la imagen original. Utiliza la función trueMatrix() para obtener la matriz real utilizada para transformar una imagen.

A diferencia de la otra sobrecarga, esta función se puede utilizar para realizar transformaciones en perspectiva sobre imágenes.

Véase también trueMatrix() y Image Transformations.

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

Devuelve la matriz real utilizada para transformar una imagen con los parámetros « width », « height » y « matrix » especificados.

Al transformar una imagen mediante la función transformed(), la matriz de transformación se ajusta internamente para compensar cualquier traslación no deseada; es decir, transformed() devuelve la imagen más pequeña que contiene todos los puntos transformados de la imagen original. Esta función devuelve la matriz modificada, que mapea correctamente los puntos de la imagen original a la nueva imagen.

A diferencia de la otra sobrecarga, esta función crea matrices de transformación que pueden utilizarse para realizar transformaciones en perspectiva sobre imágenes.

Véase también transformed() y Image Transformations.

bool QImage::valid(const QPoint &pos) const

Devuelve ` true ` si ` pos ` es un par de coordenadas válido dentro de la imagen; en caso contrario, devuelve ` false`.

Véase también rect() y QRect::contains().

bool QImage::valid(int x, int y) const

Devuelve ` true ` si ` QPoint` (`x`, ` y`) es un par de coordenadas válido dentro de la imagen; en caso contrario, devuelve ` false`.

Esta es una función sobrecargada.

int QImage::width() const

Devuelve el ancho de la imagen.

Véase también Image Information.

QImage::operator QVariant() const

Devuelve la imagen como un objeto de tipo « QVariant ».

bool QImage::operator!=(const QImage &image) const

Devuelve « true » si esta imagen y la imagen indicada en « image » tienen contenidos diferentes; en caso contrario, devuelve « false ».

La comparación puede ser lenta, a menos que haya alguna diferencia evidente, como anchos distintos, en cuyo caso la función devolverá el resultado rápidamente.

Véase también operator=().

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

Asigna « other » a esta instancia de « QImage ».

QImage &QImage::operator=(const QImage &image)

Asigna una copia superficial del objeto ` image ` indicado a esta imagen y devuelve una referencia a dicha imagen.

Para obtener más información sobre las copias superficiales, consulta la documentación sobre el intercambio implícito de datos.

Véanse también ` copy()` y ` QImage()`.

bool QImage::operator==(const QImage &image) const

Devuelve « true » si esta imagen y la especificada en « image » tienen el mismo contenido; en caso contrario, devuelve « false ».

La comparación puede ser lenta, a menos que haya alguna diferencia evidente (por ejemplo, un tamaño o formato distinto), en cuyo caso la función devolverá el resultado rápidamente.

Véase también operator=().

Elementos no miembros relacionados

QImageCleanupFunction

Una función con la siguiente firma que puede utilizarse para implementar la gestión básica de la memoria de imágenes:

void myImageCleanupHandler(void *info);

QDataStream &operator<<(QDataStream &stream, const QImage &image)

Escribe el objeto ` image ` proporcionado en el objeto ` stream ` indicado como imagen PNG, o como imagen BMP si la versión del flujo es 1. Ten en cuenta que escribir el flujo en un archivo no generará un archivo de imagen válido.

Véase también QImage::save() y Serialización de tipos de datos de Qt.

QDataStream &operator>>(QDataStream &stream, QImage &image)

Lee una imagen desde la dirección stream y la guarda en la dirección image.

Véase también QImage::load() y Serialización de tipos de datos de Qt.

© 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.