# Img module

$Id$

## Introduction

### General description

The img module is repsonsible for all image decoding and the image cache. It does not draw the images, that is done by display, it only decodes and caches them and returns bitmaps when requested.

The main purposes of the img module are

- Caches decoded images
- Decodes images (in some cases using image decoders in other modules
- Can animate between frames when requested
- Does not draw images, this is done by the doc module in core-1, and the display module in core-2
- Implements the following decoders: gif, xbm, bmp, wbmp, ico
- Related modules, jpg implemented with libjpeg in core-1, with jaypeg in core-2, png implemented with minpng in both core-1 and core-2.

### Use-cases

- Load an image in the browser
- Load a page containing images

In both these cases the image which is to be displayed by Opera will be decoded and cached by the img module.

### Design goals

The design goals of img are:

- Support both core-1 and core-2 through the same interface
- Interface compatibility with dali_1 in many cases
- Does not draw images, belongs in display code
- Does not depend on other modules (except base modules), a clean interface is defined (for example, does not reference to the url module)
- Does not animate images (that is, setting up timers, etc). This has to be decided by the document.
- Supports animations being out of sync in different documents with each other

### Supported standards

- bmp (link to specification)
- gif (specification)
- ico (link to specification)
- jpeg (through jaypeg/libjpeg modules) (specification)
- png (through minpng module) (specification)
- wbmp (specification)
- xbm (specification)

### On decoding and memory

The image module guarantees that all completely decoded lines will contain no uninitialized data. In the case of indexed color data, the platform implementing AddLine will have to bounds-check color indices.

## API documentation

The API documentation is generated by Doxygen.

## Memory handling

The memory usage and OOM handling is described in the mainpage of the API documentation.

## Implementation details

Some implementation details are described in the mainpage of the API documentation.

The core functionality of the image module is the decode images and cache them.

### Image representation

The image object in the img module contains an ImageRep. The ImageRep contains the actual data and can be shared between multiple Image object. It is the ImageRep which is stored in the image cache.

The ImageRep contains a content provider, image loader, meta data, some flags and most importently an image content. The image content can be of several different types. A null image content means the size is not yet known. There is only one null image content. An empty image content means the size is known but the image is not yet decoded. A static image content is used for images with a single frame, regardless if it is animated or not. An animated image content is used for animated images.

### Image decoding

The decoding of images is done through image decoders. The image decoders factories, which can be used to create decoders are registered in the image manager and can then be used by the image module to decode images. You can register any number of image decoders. Most of the decoder factories are included in the img module.

The image decoder factories are designed to be able to given a data stream detect if the data stream could be a supported image. This is used to determine which image decoder to use. If a factory detects a supported format it will probably be asked to create an image decoder later on.

The image decoder factories are also able to check the size of an image without creating a decoder and decoding it. This is needed to check the size of image which are not visible without spending much time on it.

The actual image decoders created by the factories must handle decoding of data without having the entire data stream. The image module will call DecodeData repeatedly with chunks of data. If the decode cannot handle all of it it must report how much data to resend.

### Image cache

The image cache in the image module caches ImageReps. The current cache strategy is to cache images on a MRU basis, but images which are visible in a document are always kept in the cache. This means that the cache can exceed the cache limit.

The image cache consists of three different lists. One list for free images, one list for decoded images which are not visible and one list for decoded images which are visible. When an image is marked as visible or not visible it is moved between the lists.