# display module documentation

- API documentation generated by doxygen

## The Text Shaper

The display module provides support for internal text shaping. Text shaping is used on arabic text - which has a cursive nature - in order to make characters look connected. This is achieved by replacing characters in the arabic unicode block with their initial, medial, isolated and final forms in the arabic presentation block. The text shaper also applies ligatures to combinations of arabic characters where a compound character exists that represents the combination.

Apart from arabic text, Opera's internal text shaper is used to swap the devanagari (dependent) vowel sign i and the syllable it changes. This has nothing to do with text shaping per se, and is done for practical reasons only, the reason being that the devanagari (dependent) vowel sign i is the only (dependent) vowel sign (in the devanagari range) that is drawn to the left of the syllable it changes.

The text shaper is active whenever the feature FEATURE_INTERNAL_TEXTSHAPER is set, and the API API_DISPLAY_TEXTSHAPER is imported.

Prior to being moved to display, the text shaper resided in docutil. There has also been some changes in how the text shaper works in relation to the text shaper in docutil. Key points are:

- Text shaping is done in logical order (as opposed to reversed).
- Text shaping is applied in TransformText (as opposed to GetStringWidth and DrawString).
- Text shaping can be done one (resulting) character at a time, so that font switching can be applied to shaped text.

### Important functions

- NeedsTransformation - determines if a string need be passed through the text shaper.
- Prepare - replaces arabic characters with their presentation forms and applies ligatures. Also swaps devanagari (dependent) vowel sign i and the syllable it modifies.
- GetShapedChar - returns one shaped character. (Don't forget to call ResetState before processing a string this way!)
- ResetState - resets the text shaper's internal joining state.

### Memory usage

#### OOM

The only function in the text shaper that can run out of memory is Prepare, in which case it will return the corresponding OP_STATUS. Thus, reporting OOM is left to the caller.

#### Stack memory

The TextShaper class uses some const arrays on the stack to store various attributes of arabic characters, as well as some other information. The current stack arrays exist:

- ligaturetable - 33 uni_chars, used to decide if a character sequence should be replaced with a ligature.
- prestable_start - 180 uni_chars, used to map arabic characters to their first presentation form.
- prestable_count - 180 UINT8s, used to determine how many presentation forms each arabic character has.
- joinclasstable - 299 enums, used to determine which type of joining each arabic and syraic character has.

#### Heap memory

The text shaper stores a TempBuffer in the DisplayModule object. This TempBuffer is set to hold the length of the input string whenever Prepare is called. Thus, the size of the TempBuffer depends on the input data. The minimum size of the TempBuffer is 30 uni_chars. Since the DisplayModule object holds the TempBuffer, it is also responsible for cleanup.