Gambas Documentation - /doc/imageconv

# Image Management In Gambas

## The pixel format problem

Image management on Linux is a tricky beast that can easily turn into nightmare because of the many different way images store their pixel data into memory.

### The different pixel formats

Here is a non-exhaustive list of different pixel formats:

Name | Description | Pixel in memory (little-endian CPU)
--- | --- | ---
`BGR` | Each pixel is three bytes (24 bits). Each byte is a colour component, blue being the lowest byte. | `RGBRGBRGB...`
`BGRX` | Each pixel is four bytes (32 bits). Three bytes are for the colour components, one byte is ignored. Blue is the lowest byte. | `-RGB-RGB-RGB...`
`BGRA` | Each pixel is four bytes (32 bits). Three bytes are for the colour components, one byte for the alpha value. Blue is the lowest byte. | `ARGBARGBARGB...`
`RGBA` | Each pixel is four bytes (32 bits). Three bytes are for the colour components, one byte for the alpha value. Red is the lowest byte. | `ABGRABGRABGR...`
`BGRP` | Each pixel is four bytes (32 bits). Three bytes are for the colour components, one byte for the alpha value. Blue is the lowest byte. The colour values are pre-multiplied by the alpha value, for performance reasons. | `PRGBPRGBPRGB...`

The name of the pixel format comes from the convention internally used by Gambas.

### Pixel formats and libraries

The problem comes when you start using all these nifty toolkits and libraries: each library want to use one or more specific pixel formats that are usually not the same as the other library.

Let's see:

Entity | Gambas component | Preferred pixel format
--- | --- | ---
QT4 image | gb.qt4 | `BGRP`. QT4 usually uses `BGRA`, but explicitly urges to use `BGRP` for performance reasons.
GTK+ pixbuf | gb.gtk, gb.gtk3 | `RGB` or `RGBA`
Cairo | gb.gtk, gb.gtk3, gb.cairo | `BGRP`
JPEG image loader | gb.image.io | `RGB`
Video device | gb.media, gb.v4l | `RGB`, usually internally translated from one of the many possible video device format (`YUV`, `RGB` on 16 bits...)
OpenGL | gb.opengl | `RGB`, `BGR`, `RGBA` or `BGRA`.
Poppler | gb.pdf | `RGB`
Gambas | gb.image | Gambas colours use `BGRA`, but the alpha component is inverted! (255 for full transparency, and 0 for full opacity).

## How Gambas deals with these pixel formats

Hopefully, Gambas manages the different pixel formats for you, thanks to the gb.image component.

### Automatic format conversion

The gb.image component automatically converts image from one pixel format to the other, according to the needs of the component that wants to use the image.

Consequently, when programming in Gambas, you can freely take an image from a video device, draw it inside a DrawingArea control, use it as an OpenGL texture, or whatever you want. You will never see the pixel formats.

To get the pixel format of an image, use the Image.Format property.

### Conversion costs

Each image conversion has a performance cost, which is proportional to the image size.

The conversion routines are optimized (but do not use assembly at all, so maybe they could be faster), but that cost cannot be neglected if the image is huge.

Especially with gb.gtk, that uses two different pixel formats (one for its images, another one when drawing with them): for example, if you load an image from the disk and draw it on the screen, a conversion will occur.

### The Image.Debug property

To check that you don't cause too many conversions, you can set the Image.Debug static property.

Then a message will be printed on the standard error output each time an image conversion occurs.

### Image processing methods

All methods of the Image class can deal with any pixel formats, with the exception of the Image.PaintImage method that only supports `RGBA` and `BGRA` formats.

But do not worry: you normally encounter pre-multiplied formats with GUI components, and so you will use the Paint.Image method instead.