First examples: SAGA PIP (ApolloPiP) and the SAGA hardware pointer (ApolloPointer)

.github/CODEOWNERS

@@ -169,6 +169,8 @@
 /core/saga-registers/sprite-collision.md @WDrijver
 /core/saga-registers/system.md @WDrijver
 /core/saga-video-isabelle/index.md @WDrijver
+/examples/saga-pip-overlay-and-chroma-key.md @WDrijver
+/examples/saga-pointer-sprite.md @WDrijver
 /hardware/index.md @WDrijver
 /os/apolloos-and-amigaos-on-v4.md @WDrijver
 /os/apolloos-specific-on-v4.md @WDrijver
@@ -187,7 +189,15 @@
 /toolchain/project-makefile.md @WDrijver
 /toolchain/target-os-headers.md @WDrijver
 /toolchain/vasm-assembler.md @WDrijver
+/toolchain/apollolib/debug.md @WDrijver
+/toolchain/apollolib/index.md @WDrijver
+/toolchain/apollolib/input.md @WDrijver
+/toolchain/apollolib/memory-and-blit.md @WDrijver
+/toolchain/apollolib/picture.md @WDrijver
+/toolchain/apollolib/sound.md @WDrijver
+/toolchain/apollolib/system-and-timing.md @WDrijver
 /toolchain/best-practices/gcc-code-generation-for-68080.md @TuKo1982
+/toolchain/pitfalls/apollolib-known-bugs.md @WDrijver
 /toolchain/pitfalls/calling-assembler-from-gcc.md @TuKo1982
 /toolchain/pitfalls/float-settings-mismatch.md @TuKo1982
 /toolchain/pitfalls/gcc-bbb-autoinc.md @TuKo1982

.github/workflows/kb-checks.yml

@@ -44,6 +44,7 @@ jobs:
     env:
       ACD_DIR: /home/runner/ApolloCrossDev
       PREFIX: /home/runner/ApolloCrossDev/Compilers/GCC-6.50-Dev
+      APOLLOLIB: /home/runner/acd-src/Projects/ApolloLib
     steps:
       - uses: actions/checkout@v4
 
@@ -52,6 +53,16 @@ jobs:
       - name: Find ApolloCrossDev commit
         id: acd
         run: echo "sha=$(git ls-remote https://github.com/WDrijver/ApolloCrossDev refs/heads/main | cut -f1)" >> "$GITHUB_OUTPUT"
+      # Snippets may include ApolloLib's headers: fetch only Projects/ApolloLib
+      # of the same commit (a few hundred KB), also when the toolchain is cached.
+      - name: Fetch ApolloLib
+        run: |
+          git init -q /home/runner/acd-src
+          cd /home/runner/acd-src
+          git sparse-checkout set --no-cone Projects/ApolloLib
+          git fetch -q --depth 1 --filter=blob:none https://github.com/WDrijver/ApolloCrossDev ${{ steps.acd.outputs.sha }}
+          git checkout -q FETCH_HEAD
+          test -f "$APOLLOLIB/ApolloCrossDev_Lib.h"
       - name: Restore ApolloCrossDev
         id: cache
         uses: actions/cache/restore@v4

core/best-practices/prefer-library-calls-for-saga-chips.md

@@ -13,6 +13,7 @@ tags: [saga, arne, isabelle, maggie, library, apollolib, maggie-library, registe
 related:
   - core/saga-registers/index.md
   - os/libraries/maggie-library.md
+  - toolchain/apollolib/index.md
   - core/saga-audio-arne/index.md
   - core/saga-video-isabelle/index.md
   - core/saga-3d-maggie/index.md
@@ -41,7 +42,10 @@ For the SAGA chips, prefer the library calls to direct register access
 
 - An official library for Arne and Isabelle is in development. Until it is
   released, ApolloLib is the best choice for library calls to Arne and
-  Isabelle.
+  Isabelle. It is described in
+  [toolchain/apollolib/](../../toolchain/apollolib/index.md); check its
+  [fixed bugs and remaining limits](../../toolchain/pitfalls/apollolib-known-bugs.md)
+  first.
 - maggie.library is described in
   [os/libraries/maggie-library.md](../../os/libraries/maggie-library.md).
   When you need more than that file covers, the author's repository is the

core/saga-registers/arne-channels.md

@@ -17,7 +17,7 @@ related:
   - core/best-practices/prefer-library-calls-for-saga-chips.md
 sources:
   - "SAGA register documentation, sources/official/saga-registers/ (HTML)"
-  - "ApolloLib, github.com/WDrijver/ApolloCrossDev Projects/ApolloLib (ApolloCrossDev_Defines.h, ApolloCrossDev_LibC.c), commit 2dfaa5c (2026-09-02)"
+  - "ApolloLib, github.com/WDrijver/ApolloCrossDev Projects/ApolloLib (ApolloCrossDev_Defines.h, ApolloCrossDev_LibC.c), commit ad7f0b4 (2026-11-04)"
   - "WDrijver (maintainer), answers on the SAGA register documentation, 2026-11-04"
   - "Gunnar (core developer, BigGun), Apollo chat, 2026-11-04 (relayed by WDrijver)"
 generated_from: sources/official/saga-registers/index.htm

core/saga-registers/chunky-plane.md

@@ -15,7 +15,7 @@ related:
   - core/best-practices/prefer-library-calls-for-saga-chips.md
 sources:
   - "SAGA register documentation, sources/official/saga-registers/ (HTML)"
-  - "ApolloLib, github.com/WDrijver/ApolloCrossDev Projects/ApolloLib (ApolloCrossDev_Defines.h, ApolloCrossDev_LibC.c), commit 2dfaa5c (2026-09-02)"
+  - "ApolloLib, github.com/WDrijver/ApolloCrossDev Projects/ApolloLib (ApolloCrossDev_Defines.h, ApolloCrossDev_LibC.c), commit ad7f0b4 (2026-11-04)"
   - "maggie.library samples, see os/libraries/maggie-library.md"
 generated_from: sources/official/saga-registers/index.htm
 ---

core/saga-registers/colour-ports.md

@@ -15,7 +15,7 @@ related:
   - core/best-practices/prefer-library-calls-for-saga-chips.md
 sources:
   - "SAGA register documentation, sources/official/saga-registers/ (HTML)"
-  - "ApolloLib, github.com/WDrijver/ApolloCrossDev Projects/ApolloLib (ApolloCrossDev_Defines.h, ApolloCrossDev_LibC.c), commit 2dfaa5c (2026-09-02)"
+  - "ApolloLib, github.com/WDrijver/ApolloCrossDev Projects/ApolloLib (ApolloCrossDev_Defines.h, ApolloCrossDev_LibC.c), commit ad7f0b4 (2026-11-04)"
   - "Gunnar (core developer, BigGun), Apollo chat, 2026-11-04 (relayed by WDrijver)"
 generated_from: sources/official/saga-registers/index.htm
 ---

core/saga-registers/index.md

@@ -14,7 +14,7 @@ related:
   - core/best-practices/prefer-library-calls-for-saga-chips.md
 sources:
   - "SAGA register documentation, sources/official/saga-registers/ (HTML)"
-  - "ApolloLib, github.com/WDrijver/ApolloCrossDev Projects/ApolloLib (ApolloCrossDev_Defines.h, ApolloCrossDev_LibC.c), commit 2dfaa5c (2026-09-02)"
+  - "ApolloLib, github.com/WDrijver/ApolloCrossDev Projects/ApolloLib (ApolloCrossDev_Defines.h, ApolloCrossDev_LibC.c), commit ad7f0b4 (2026-11-04)"
   - "WDrijver (maintainer), answers on the SAGA register documentation, 2026-11-04"
   - "Gunnar (core developer, BigGun), Apollo chat, 2026-11-04 (relayed by WDrijver)"
 generated_from: sources/official/saga-registers/index.htm

core/saga-registers/input.md

@@ -15,7 +15,7 @@ related:
   - core/best-practices/prefer-library-calls-for-saga-chips.md
 sources:
   - "SAGA register documentation, sources/official/saga-registers/ (HTML)"
-  - "ApolloLib, github.com/WDrijver/ApolloCrossDev Projects/ApolloLib (ApolloCrossDev_Defines.h, ApolloCrossDev_LibC.c), commit 2dfaa5c (2026-09-02)"
+  - "ApolloLib, github.com/WDrijver/ApolloCrossDev Projects/ApolloLib (ApolloCrossDev_Defines.h, ApolloCrossDev_LibC.c), commit ad7f0b4 (2026-11-04)"
 generated_from: sources/official/saga-registers/index.htm
 ---
 

core/saga-registers/pip.md

@@ -17,8 +17,8 @@ related:
   - core/best-practices/prefer-library-calls-for-saga-chips.md
 sources:
   - "SAGA register documentation, sources/official/saga-registers/ (HTML)"
-  - "ApolloLib, github.com/WDrijver/ApolloCrossDev Projects/ApolloLib (ApolloCrossDev_Defines.h, ApolloCrossDev_LibC.c), commit 2dfaa5c (2026-09-02)"
-  - "Example SAGAPiP.c, github.com/WDrijver/ApolloCrossDev Projects/SAGAPiP, commit 2dfaa5c (2026-09-02)"
+  - "ApolloLib, github.com/WDrijver/ApolloCrossDev Projects/ApolloLib (ApolloCrossDev_Defines.h, ApolloCrossDev_LibC.c), commit ad7f0b4 (2026-11-04)"
+  - "Example ApolloPiP.c (formerly SAGAPiP), github.com/WDrijver/ApolloCrossDev Projects/ApolloPiP, commit ad7f0b4 (2026-11-04)"
   - "WDrijver (maintainer), answers on the SAGA register documentation, 2026-11-04"
 generated_from: sources/official/saga-registers/index.htm
 ---
@@ -45,7 +45,7 @@ SAGA overlays up to two picture-in-picture windows (PIP) on the main screen, eac
 | `$DFF3E0` | PipColorKey | W | ColorKey 1000,RRRR,GGGG,BBBB |
 | `$DFF3E2` | PipDMARowLen | W | PipDMARowLen |
 
-The original links these rows to a page that doesn't exist; the facts below come from ApolloLib and the SAGAPiP example (SRC).
+The original links these rows to a page that doesn't exist; the facts below come from ApolloLib and the ApolloPiP example (SRC).
 
 ### PIP 2 registers (SRC, not in the original)
 
@@ -63,7 +63,7 @@ PIP 2 has the same layout as PIP 1, `$20` lower (ApolloLib):
 | `$DFF3C0` | PIP2 colour key | `$DFF3E0` |
 | `$DFF3C2` | PIP2 DMA row length | `$DFF3E2` |
 
-Its colour port is `$DFF37C` (see [colour-ports.md](colour-ports.md)). The SAGAPiP example says two PIPs exist from Core 11900 (SRC).
+Its colour port is `$DFF37C` (see [colour-ports.md](colour-ports.md)). The ApolloPiP example says two PIPs exist from Core 11900 (SRC).
 
 ### Register meanings (SRC)
 
@@ -90,7 +90,7 @@ Its colour port is `$DFF37C` (see [colour-ports.md](colour-ports.md)). The SAGAP
 
 Formats and transparent colours: WDrijver, 2026-11-04. The transparent colour is fixed per format. ApolloLib still marks YUV as not supported on PIP; that is an error in ApolloLib, not in the hardware.
 
-### Two modes (SAGAPiP example, SRC)
+### Two modes (ApolloPiP example, SRC)
 
 - **Overlay:** colour key 0. The PIP is in front of the main screen; with format bit 8 set, pixels in the transparent colour of the format are transparent.
 - **Chroma key:** colour key with bit 15 set, for example `$8F0F` (purple). The PIP is behind the main screen and shows only where the main screen has the key colour.

core/saga-registers/pointer.md

@@ -15,9 +15,9 @@ related:
   - core/best-practices/prefer-library-calls-for-saga-chips.md
 sources:
   - "SAGA register documentation, sources/official/saga-registers/ (HTML)"
-  - "ApolloLib, github.com/WDrijver/ApolloCrossDev Projects/ApolloLib (ApolloCrossDev_Defines.h, ApolloCrossDev_LibC.c), commit 2dfaa5c (2026-09-02)"
+  - "ApolloLib, github.com/WDrijver/ApolloCrossDev Projects/ApolloLib (ApolloCrossDev_Defines.h, ApolloCrossDev_LibC.c), commit ad7f0b4 (2026-11-04)"
   - "ApolloLib, older copy in ApolloClaude docs/toolchain/_ApolloLib (ApolloCrossDev_Defines.h), 2026-11-04"
-  - "Example ApolloPointer.c, github.com/WDrijver/ApolloCrossDev Projects/ApolloPointer, commit 2dfaa5c (2026-09-02)"
+  - "Example ApolloPointer.c, github.com/WDrijver/ApolloCrossDev Projects/ApolloPointer, commit ad7f0b4 (2026-11-04)"
   - "WDrijver (maintainer), answers on the SAGA register documentation, 2026-11-04"
 generated_from: sources/official/saga-registers/index.htm
 ---

examples/saga-pip-overlay-and-chroma-key.md

@@ -0,0 +1,136 @@
+---
+title: SAGA PIP in overlay and chroma-key mode (from the ApolloPiP example)
+type: example
+owner: WDrijver
+status: draft
+origin: ai-assisted
+basis: [source-code]
+components: [saga-video-isabelle, toolchain]
+applies_to:
+  core: "Core 12000+"
+  os: [any]
+tags: [saga, isabelle, pip, overlay, chroma-key, apollolib, example]
+related:
+  - core/saga-registers/pip.md
+  - core/saga-registers/colour-ports.md
+  - toolchain/apollolib/picture.md
+  - core/best-practices/prefer-library-calls-for-saga-chips.md
+sources:
+  - "Example ApolloPiP.c (formerly SAGAPiP), github.com/WDrijver/ApolloCrossDev Projects/ApolloPiP, commit ad7f0b4 (2026-11-04)"
+  - "ApolloLib, github.com/WDrijver/ApolloCrossDev Projects/ApolloLib, commit ad7f0b4 (2026-11-04)"
+---
+
+## Purpose
+
+Show a picture-in-picture (PIP) window on top of the screen (overlay mode)
+and behind it (chroma-key mode), with ApolloLib. The code below is the PIP
+part of ApolloCrossDev's ApolloPiP example, in three functions:
+
+- `ShowPiP1Overlay`: an 8-bit PIP in front of the screen; palette index
+  `$FF` is transparent.
+- `ShowPiP1Behind`: a 16-bit PIP behind the screen, visible where the
+  screen is purple (the chroma key).
+- `HidePiP1`: PIP 1 off.
+
+The full ApolloPiP program does more: it plays a soundtrack, shows a
+1280x720 background, opens a Workbench window, lays PIP 1 and PIP 2 over
+it and follows the window when it moves (see "The full example" below).
+
+## Build
+
+The functions compile as a library unit. In a project that uses ApolloLib
+(see [toolchain/apollolib/index.md](../toolchain/apollolib/index.md)):
+
+```sh
+m68k-amigaos-gcc -noixemul -O2 -m68080 -m68881 -ffast-math -fomit-frame-pointer -Wall \
+  -I$APOLLOLIB -c pip.c -o pip.o
+```
+
+The full example builds in ApolloCrossDev with `make` in
+`Projects/ApolloPiP` (which also uploads it to the Apollo V4), or
+`make cleanbefore build` to only build.
+
+## Code
+
+```c
+// kb:compile
+/* SAGA PIP with ApolloLib: overlay and chroma-key mode, after the ApolloPiP
+   example in ApolloCrossDev Projects/ApolloPiP. Needs ApolloLib a9a994f+:
+   from there ApolloShowPiP1 also loads the palette of an 8-bit picture. */
+#include "ApolloCrossDev_Lib.h"
+
+#define PIP1_REG(a) (*(volatile UWORD *)(a))
+
+/* Overlay mode: PIP 1 lies in front of the screen at (left, top). With the
+   transparency bit, palette index $FF is transparent. */
+void ShowPiP1Overlay(struct ApolloPicture *pic, WORD left, WORD top)
+{
+    *(volatile ULONG *)APOLLO_SAGA_PIP1_POINTER = (ULONG)(pic->buffer + pic->position);
+    PIP1_REG(APOLLO_SAGA_PIP1_X_START) = left + 16;             /* +16 and -1: as in ApolloPiP */
+    PIP1_REG(APOLLO_SAGA_PIP1_X_STOP)  = left + pic->width + 16;
+    PIP1_REG(APOLLO_SAGA_PIP1_Y_START) = top - 1;
+    PIP1_REG(APOLLO_SAGA_PIP1_Y_STOP)  = top + pic->height - 1;
+    PIP1_REG(APOLLO_SAGA_PIP1_GFXMODE) = APOLLO_SAGA_PIP_TRANSON | APOLLO_SAGA_8_INDEX;
+    PIP1_REG(APOLLO_SAGA_PIP1_MODULO)  = 0;
+    PIP1_REG(APOLLO_SAGA_PIP1_CLRKEY)  = 0x0000;                /* 0 = overlay mode */
+    ApolloShowPiP1(pic);                                        /* palette, then DMA row length: PIP on */
+}
+
+/* Chroma-key mode: PIP 1 lies behind the screen and shows only where the
+   screen has the key colour, here purple ($F0F in RGB444). */
+void ShowPiP1Behind(struct ApolloPicture *pic16, WORD width, WORD height)
+{
+    *(volatile ULONG *)APOLLO_SAGA_PIP1_POINTER = (ULONG)(pic16->buffer + pic16->position);
+    PIP1_REG(APOLLO_SAGA_PIP1_X_START) = 16;
+    PIP1_REG(APOLLO_SAGA_PIP1_X_STOP)  = width + 16;
+    PIP1_REG(APOLLO_SAGA_PIP1_Y_START) = 0;
+    PIP1_REG(APOLLO_SAGA_PIP1_Y_STOP)  = height;
+    PIP1_REG(APOLLO_SAGA_PIP1_GFXMODE) = APOLLO_SAGA_16_R5G6B5;
+    PIP1_REG(APOLLO_SAGA_PIP1_MODULO)  = 0;
+    PIP1_REG(APOLLO_SAGA_PIP1_CLRKEY)  = 0x8F0F;                /* bit 15 = on, R=$F G=$0 B=$F */
+    ApolloShowPiP1(pic16);
+}
+
+/* Switch PIP 1 off: DMA row length 0. */
+void HidePiP1(void)
+{
+    ApolloHidePiP1();
+}
+```
+
+Load the pictures with `ApolloLoadPicture` first: an 8-bit BMP for the
+overlay, a 16-bit DDS (R5G6B5) for the background.
+
+## Expected result
+
+- **Overlay:** after `ShowPiP1Overlay(&pic, left, top)` the 8-bit picture
+  appears over the screen, its top-left corner at (`left`, `top`) in
+  screen pixels. Pixels with palette index `$FF` show the screen behind.
+- **Chroma key:** after `ShowPiP1Behind(&bg, 1280, 720)` the screen looks
+  unchanged, except where it is purple (`$F0F`): there the PIP shows
+  through. ApolloPiP fills a Workbench window with purple to look through it.
+- **Off:** after `HidePiP1()` the PIP is gone.
+
+## The full example
+
+`Projects/ApolloPiP/ApolloPiP.c` (ApolloCrossDev commit ad7f0b4; called SAGAPiP before 2026-11-04) does more than
+the code above: soundtrack, background picture, a Workbench window with
+PIP 1 and PIP 2 on it that follow the window, and a click that punches a
+transparent square into the overlay.
+
+ApolloCrossDev pull request #19 (2026-11-04) fixed these problems of the
+earlier version. Keep them out of your own code:
+
+| Earlier problem | Effect | Now |
+|---|---|---|
+| No PIP palette loaded | 8-bit overlays in the wrong colours, since ApolloLib 789cbcc (2026-06-16) dropped the palette preload in `ApolloLoadPicture` | `ApolloShowPiP1/2` load it |
+| Positional initializers for `struct ApolloPicture` | Since `palette` is an array, the last value went into `palette[2]`, not `target` | Fields set by name |
+| Workbench restored as GFXMODE `$0A04` | Worked only on a 1280x720, 24-bit Workbench | Mode, pointer and modulo saved from `$DFE1F4`/`$DFE1EC`/`$DFE1E6` and restored |
+| `if (!&pipwindow)` | A failed `OpenWindowTags` went unnoticed | `if (!pipwindow)` |
+| `BMF_DISPLAYABLE \| BMB_CLEAR \| BMB_HIJACKED \| …` | `BMB_` are bit numbers: the flags became `$F` | `BMF_DISPLAYABLE \| BMF_CLEAR \| BMF_INTERLEAVED` |
+| Five exit labels, uninitialized structures | Freed buffers that were never loaded; read uninitialized fields | Everything starts cleared; one exit path frees only what was acquired |
+| cybergraphics.library never closed | Leak | Closed |
+| `ApolloCPUDelay` under Workbench | Busy waits | `Delay()` |
+
+The +16 (X) and −1 (Y) corrections place the PIP exactly over a Workbench
+window in ApolloPiP; they are not documented elsewhere.