![[Burning Cog]](../../../icons/pyromaniac.png){kind=icon}
Introduction and Overview
SuperSample is a module which converts monochrome source image data into 4 bits-per-pixel destination image data while reducing the image size. It is intended for use by the Font Manager when generating anti-aliased font output from 1 bit-per-pixel source images.
The module provides two SWIs. SWI Super_Sample90 is used for images with a 1:1 pixel aspect ratio, and SWI Super_Sample45 is used for images with a 1:2 pixel aspect ratio. Both calls are internal interfaces and should not be used by application software.
Technical Details
Both SWIs treat the source image as a packed 1 bit-per-pixel bitmap and write packed 4 bits-per-pixel output. The calls reduce the source by sampling output points spaced four source pixels apart in both directions. The source width and height are therefore expected to be 4n+3 pixels, allowing each output sample to be centred on source position 3,3 and then advanced in steps of four pixels without any special edge handling.
Source bitmap
The source bitmap is described by a pointer, a line spacing and a row count. The source words are read least significant bit first. The line spacing is the number of bytes between source rows, and must be word aligned.
The source row format is:
| Offset | Size | Contents |
|---|---|---|
| 0 | 4 | First 32 source pixels in the row, with the leftmost pixel in bit 0. |
| 4 | 4 | Next 32 source pixels in the row, in the same bit order. |
| 8- | 4 | Further source words, if present. |
The last bit of each source row is unused. A row therefore describes (8 * line spacing) - 1 source pixels, which is one less than a multiple of eight pixels and so satisfies the 4n+3 width requirement.
Destination bitmap
The destination bitmap is described by a pointer only. Output rows are written consecutively, and each destination row occupies the same number of bytes as the source line spacing. This is one 32 bit destination word for every 32 bits of source row storage. Each output word contains up to eight 4 bit pixels, least significant nibble first.
The destination row format is:
| Offset | Size | Contents |
|---|---|---|
| 0 | 4 | First seven or eight destination pixels in the row, with the leftmost pixel in bits 3-0. |
| 4 | 4 | Next eight destination pixels in the row, in the same nibble order. |
| 8- | 4 | Further destination words, if present. |
The number of destination rows generated is (source row count - 3) / 4. Each row contains (2 * line spacing) - 1 destination pixels, so the final nibble of the row is unused. If the source row count is 3, the call returns without writing any output.
Sampling for square pixels
SWI Super_Sample90 calculates each output pixel from a 7 by 7 source pixel grid centred on the output sample point. The weights are:
| Row | Weights |
|---|---|
| 1 | 1, 2, 3, 4, 3, 2, 1 |
| 2 | 2, 4, 6, 8, 6, 4, 2 |
| 3 | 3, 6, 9, 12, 9, 6, 3 |
| 4 | 4, 8, 12, 16, 12, 8, 4 |
| 5 | 3, 6, 9, 12, 9, 6, 3 |
| 6 | 2, 4, 6, 8, 6, 4, 2 |
| 7 | 1, 2, 3, 4, 3, 2, 1 |
The maximum weighted total is 256. The total is rounded by adding 14 and then the high nibble is used as the 4 bit destination pixel value. Values which would overflow the 4 bit range are clamped to 15. In module versions from 0.06 onwards, very light pixels which would produce value 1 are forced to 0.
Sampling for double-height pixels
SWI Super_Sample45 calculates each output pixel from a 9 by 7 source pixel grid. The weights are:
| Row | Weights |
|---|---|
| 1 | 0, 0, 0, 0, 1, 0, 0, 0, 0 |
| 2 | 1, 2, 4, 6, 6, 6, 4, 2, 1 |
| 3 | 1, 4, 8, 12, 13, 12, 8, 4, 1 |
| 4 | 1, 4, 8, 12, 14, 12, 8, 4, 1 |
| 5 | 1, 4, 8, 12, 13, 12, 8, 4, 1 |
| 6 | 1, 2, 4, 6, 6, 6, 4, 2, 1 |
| 7 | 0, 0, 0, 0, 1, 0, 0, 0, 0 |
The maximum weighted total, rounding and clamping rules are the same as for SWI Super_Sample90.
SWI Calls
| R1 | = | Pointer to the packed 1 bit-per-pixel source bitmap. |
| R2 | = | Source row spacing in bytes. This must be word aligned. |
| R3 | = | Number of source rows. This must be 4n+3. |
| R4 | = | Pointer to the packed 4 bits-per-pixel destination bitmap. |
| R0 | corrupted | |
| R1 - R11 | preserved | |
| V flag | Clear if the conversion completed; set if an error occurred, in which case R0 points to an error block. | |
This call converts the source data using the 7 by 7 square-pixel sampling kernel described in Sampling for square pixels. It is an internal interface used by the Font Manager. Application software should not rely on it.
The caller must provide enough destination storage for ((R3 - 3) / 4) rows of R2 bytes each. If R3 is 3, no output is written and the call returns successfully.
| R1 | = | Pointer to the packed 1 bit-per-pixel source bitmap. |
| R2 | = | Source row spacing in bytes. This must be word aligned. |
| R3 | = | Number of source rows. This must be 4n+3. |
| R4 | = | Pointer to the packed 4 bits-per-pixel destination bitmap. |
| R0 | corrupted | |
| R1 - R11 | preserved | |
| V flag | Clear if the conversion completed; set if an error occurred, in which case R0 points to an error block. | |
This call converts the source data using the 9 by 7 double-height-pixel sampling kernel described in Sampling for double-height pixels. It is an internal interface used by the Font Manager. Application software should not rely on it.
The caller must provide enough destination storage for ((R3 - 3) / 4) rows of R2 bytes each. If R3 is 3, no output is written and the call returns successfully.
Error Messages
This error is returned if the source row count in R3 is not 4n+3 or if the source row spacing in R2 is not word aligned.