mirror of https://github.com/alfishe/amiga-bootcamp.git synced 2026-06-13 00:26:28 +00:00

Ilia Sharin c4522ef2ed Add memory types article, expand blitter cookbook, update cross-references

New articles:
- 01_hardware/common/memory_types.md: comprehensive Chip/Fast/Slow RAM reference
  with DMA accessibility matrix, per-model configurations (A500-A4000),
  accelerator memory expansion (classic + modern), adaptive software behavior,
  pitfalls with impact analysis, FPGA/emulation notes
- AGENTS.md: documentation standards and methodology guidelines

Blitter programming (08_graphics/blitter_programming.md):
- Rewrote minterm truth table with narrative explanation and worked  example
- Added 7 advanced use cases with assembly/C code: shifted BOB, hardware scroll,
  area fill polygon, interleaved bitplane BOBs, double-buffered game loop,
  GUI window drag, tile map renderer
- Added Good/Bad Patterns section with 5 named antipatterns
- Added Practical Limitations table (10 constraints with workarounds)
- Expanded Common Minterms table with Description and Real-World Use Case columns

Cross-reference updates:
- Root README: added memory types to coverage, quick start, section index
- 01_hardware/README: updated common/ folder description
- address_space.md: linked to memory_types.md and chip_ram_expansion.md
- memory_management.md (exec): linked to hardware memory types reference
- bitmap.md, sprites.md, animation.md, audio.md: linked to memory_types.md
  explaining DMA Chip RAM requirement for each subsystem
- chip_ram_expansion.md: linked to comprehensive memory types article

2026-04-25 14:12:46 -04:00

3.2 KiB

Raw Blame History

← Home · Graphics

BitMap — Planar Bitmap Structure and Layout

Overview

Amiga display memory uses planar layout: each bitplane is a separate contiguous memory region. A pixel's colour index is formed by reading one bit from each plane at the same x,y position. This is fundamentally different from chunky (packed-pixel) or interleaved formats.

struct BitMap

/* graphics/gfx.h — NDK39 */
struct BitMap {
    UWORD  BytesPerRow;    /* bytes per row per plane (must be even) */
    UWORD  Rows;           /* height in pixels */
    UBYTE  Flags;          /* BMF_* flags */
    UBYTE  Depth;          /* number of bitplanes (1–8) */
    UWORD  pad;
    PLANEPTR Planes[8];    /* pointers to each bitplane buffer */
};

BMF_ Flags

#define BMF_CLEAR        (1<<0)  /* clear planes on allocation */
#define BMF_DISPLAYABLE  (1<<1)  /* allocated in displayable (Chip) RAM */
#define BMF_INTERLEAVED  (1<<2)  /* planes are interleaved in memory */
#define BMF_STANDARD     (1<<3)  /* use standard allocation */
#define BMF_MINPLANES    (1<<4)  /* minimum number of planes */

Planar Memory Layout

For a 320×256×4 display (16 colours):

BytesPerRow = 320/8 = 40 bytes
Rows = 256
Depth = 4

Plane 0: 40 × 256 = 10,240 bytes  (bit 0 of colour index)
Plane 1: 40 × 256 = 10,240 bytes  (bit 1)
Plane 2: 40 × 256 = 10,240 bytes  (bit 2)
Plane 3: 40 × 256 = 10,240 bytes  (bit 3)

Total = 4 × 10,240 = 40,960 bytes

Pixel colour at (x, y):

bit0 = (Planes[0][y * BytesPerRow + x/8] >> (7 - x%8)) & 1
bit1 = (Planes[1][y * BytesPerRow + x/8] >> (7 - x%8)) & 1
bit2 = (Planes[2][y * BytesPerRow + x/8] >> (7 - x%8)) & 1
bit3 = (Planes[3][y * BytesPerRow + x/8] >> (7 - x%8)) & 1
colour_index = (bit3 << 3) | (bit2 << 2) | (bit1 << 1) | bit0

Allocation

/* OS 3.0+ — AllocBitMap: */
struct BitMap *bm = AllocBitMap(320, 256, 4,
                                BMF_CLEAR | BMF_DISPLAYABLE, NULL);
/* Always in Chip RAM when BMF_DISPLAYABLE */

/* Manual allocation (OS 1.x compatible): */
struct BitMap bm;
InitBitMap(&bm, 4, 320, 256);
for (int i = 0; i < 4; i++)
    bm.Planes[i] = AllocRaster(320, 256);  /* MEMF_CHIP */

/* Free: */
FreeBitMap(bm);  /* or FreeRaster per plane */

Interleaved BitMaps

With BMF_INTERLEAVED, all planes are stored sequentially row by row:

Row 0, Plane 0: 40 bytes
Row 0, Plane 1: 40 bytes
Row 0, Plane 2: 40 bytes
Row 0, Plane 3: 40 bytes
Row 1, Plane 0: 40 bytes
...

BytesPerRow becomes 40 × Depth = 160, and each Planes[i] pointer is offset by i * 40 from the base. This layout is more cache-friendly and allows single-pass blits.

AGA 8-Bit Bitmaps

AGA (A1200/A4000) supports up to 8 bitplanes = 256 colours:

struct BitMap *bm = AllocBitMap(320, 256, 8, BMF_CLEAR | BMF_DISPLAYABLE, NULL);
/* 8 planes × 10,240 = 81,920 bytes of Chip RAM */

References

NDK39: graphics/gfx.h
ADCD 2.1: AllocBitMap, FreeBitMap, InitBitMap
HRM: Amiga Hardware Reference Manual — bitplane DMA chapter
See also: memory_types.md — why bitmaps must be in Chip RAM (DMA accessibility)

3.2 KiB Raw Blame History Unescape Escape