KITAQGB

Temporarily select a ROM bank, copy len bytes from src to dst in increasing address order, then restore the compiler’s saved ROM bank. __farmemcpy and __far_memcpy use the same implementation on this platform.

Syntax

void __farmemcpy(void* dst, u8 bank, const void* src, u16 len);

Parameters

dst

Destination in writable memory. Reserve enough space for every byte copied. Except for a zero-byte transfer, a null or invalid destination is not checked.

bank

8-bit bank selector for the source ROM mapping. Use a bank supported by the cartridge and the compiler’s bank layout; this argument is separate from the source address.

src

Near pointer to readable source bytes in the selected ROM bank. It does not contain a bank number.

len

Byte count, 0–65535. Zero performs no memory copy, but the bank-selection and restoration steps still run.

Return value

None (void).

Conditions and limits

Keep the full source range in the intended ROM mapping and the full destination range in writable memory. Copying does not select the next bank at a window boundary, handle overlapping ranges like memmove, or provide VRAM-safe writes. Use the graphics transfer APIs for VRAM.

The samples place calling code in fixed bank 0 so source-bank changes cannot unmap the code being executed. These transfers are synchronous. Do not interrupt a transfer with another bank-changing copy or assume the helper makes a whole application interrupt-safe.

The GB helper restores the compiler’s ROM-bank shadow. Use __bankswitch to maintain it; raw writes to the mapper do not update that shadow. Its saved-bank slot in HRAM is shared, so nested transfers that overwrite it are unsafe.

Usage example

__farmemcpy(buffer,payload_bank,payload_pointer,32);
expect(*asset_bank_marker==0xA1,27); // Source bank 2 was selected only for the copy.
for(i=0;i<32;i++) expect(buffer[(__safe_index u8)i]==expected_shape_byte(i),28);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Copy two patterns, 32 bytes, from payload bank 2 while bank 1 is initially selected. The program compares every copied byte, checks that bank 1 is restored and verifies that a zero-length copy leaves a 0x55 sentinel unchanged.

Expected image: a red row starts at pixel (16,32) and spans 72×8 pixels. It repeats an 8×8 triangle, an 8×8 square outline with a one-pixel border, and a tile with its left four columns filled, three times. The triangle grows from one pixel at the top left to eight pixels on its bottom row.

On GB, a blue triangle and outline at (16,64) show the __farmemcpy result; a green pair at (16,96) shows __far_memcpy. Each pair occupies 16×8 pixels. CGB shows these colors; DMG shows the same shapes in black on white.

Expected status: FAILED CHECKS 000 and FIRST FAILURE 00. The verification runs 300 frames and compares text, shape masks and colors against these expectations. This is emulator evidence, not a physical-hardware test.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\asset_banks.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\asset_banks.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

__vram_copy is a compiler alias for __vram_memcpy. It uses the same byte-count argument and the same immediate CPU transfer, including its LCD-access rules.

Copy len bytes from src to dst immediately, in increasing address order. The function returns after the copy finishes; it does not enqueue work. Source and destination advance by one byte, without tilemap row strides or tile-format conversion.

Syntax

void __vram_copy(u16 dst, const void* src, u16 len);

Parameters

dst

First destination byte address, normally in VRAM 0x8000–0x9FFF. Keep the entire span valid. CGB uses the current VRAM bank; bank 0 contains tile numbers and bank 1 contains map attributes. These routines do not choose a map from LCDC, wrap rows or allocate VRAM.

src

Source byte pointer, valid and mapped for the whole call. Data is read immediately; it is not retained for a later flush. The source bank is not switched automatically. Use non-overlapping spans: this forward copy does not provide memmove semantics.

len

Number of consecutive bytes, 0–65535. It is not a tile count. Keep the complete address range inside valid source and writable destination storage; the API does not check bounds or prevent 16-bit address wrap.

Return value

None (void).

Conditions and limits

With the LCD on, each byte write waits for STAT mode 0 or 1 under DI and is followed by EI. With the LCD off, a plain CPU loop is used. The call can span frames, does not preserve an interrupt-disabled entry state, and does not program DMA registers. Zero length performs no data transfer.

Usage example

__vram_copy(0x9862,strip,3); // The copy alias uses the same CPU transfer.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This example uses __vram_copy to place three map bytes at tile (2,3), pixel (16,24). Expect the three patterns [1,2,3] from left to right in a 24 × 8 area. Neighboring cells must remain blank. The full program places each tested copy or fill on its own row.

The supplied original graphics use tile 1 for a solid 8 × 8 square, tile 2 for its left four columns, and tile 3 for a left-aligned triangle that widens by one pixel per row from 1 to 8 pixels. DMG uses black on white; CGB distinguishes the operations with colors while keeping text black.

The square at pixel (16,88) must remain after zero-length safe and unsafe calls. With the LCD on, safe copy and fill add squares at (16,96) and (32,96). FAILED CHECKS must read 000. The emulator tests compare the drawn pixels as well as the counter. CGB uses bank 0 in this example; other banks and physical hardware are not tested here.

In CGB mode, the operation rows from MEMCPY through FILL UNSAFE cycle through red, blue and green. The ZERO COUNT square is red. In LCD ON, the left square is blue and the right square is green. Text stays black. The checks verify these colors at every drawn pixel.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\vram_memory_shapes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\vram_memory_shapes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Invoke a zero-argument callback at a runtime address in the supplied bank. The fixed-ROM helper saves each caller's bank on the CPU stack and restores it on return. The intrinsic returns no value.

Syntax

void __farcall_ptr(u8 bank, const void* func);

Parameters

bank

An unsigned 8-bit ROM-bank number. For a call, it must agree with the function's placement; for a read, it selects the source mapping. Use the target cartridge's valid range.

func

A valid executable address for a callback with no parameters. A function name or runtime pointer may supply it. Null pointers and a wrong bank/address combination are not checked at runtime.

Return value

None (void).

Conditions and limits

These calls do not forward user arguments or make the callback interrupt-reentrant. Keep the callback's own data, stack and interrupt use valid. The bank-restoring call paths are tested with nested calls and repeated calls; physical hardware and arbitrary interrupt interleavings are not covered by this example.

These GB bank interfaces carry eight bank bits and do not set the ninth MBC5 bank bit. Cartridge rules still apply, including mapper-specific treatment of bank zero. The example explicitly uses MBC5 banks 1–3; do not mix this state with untracked raw mapper writes.

Usage example

requested_bank=3;requested_callback=callback;
__farcall_ptr(requested_bank,requested_callback); // Runtime bank and address.
bank_expect(callback_count==3 && callback_byte==0xD3,17);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

At this point in the complete program, __farcall_ptr raises callback_count to 3. The callback reads D3 from bank 3. A later near read of B2 from home2 verifies that execution returned with bank 2 mapped.

The complete program teaches how a bank number and near address identify data, how callbacks cross banks, and how to distinguish the library's record from the actual mapping. All displayed numbers are hexadecimal. BANK IN and BANK OUT must show 02, BYTE HEX D3, WORD HEX 5C7A, and both FAILED CHECKS and FIRST FAILURE 00. CGB and FC display blue text; DMG displays black text.

CALL COUNT is 03: far_call, __farcall and __farcall_ptr each invoke the callback once.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\banked_data_calls.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

if (funcName == "__farcall_ptr")
            {
                if (args.Length != 2) Error(expr, "__farcall_ptr(bank, func) expects 2 arguments");
                CType callbackType = TypeOf(args[1]);
                if (callbackType.IsPointer) callbackType = callbackType.Subtype;
                if (callbackType != null && callbackType.IsFunction &&
                    (callbackType.ParamTypes ?? Array.Empty<CType>()).Length != 0)
                    Error(expr, "__farcall_ptr requires a callback with no parameters");
                CompileIntoA(args[0]);
                EmitAsm("PUSH_AF");
                CompileIntoHL(args[1]);
                EmitAsm("POP_AF");
                UseFarCallPointerBank0Helper = true;
                EmitAsm("CALL", new AsmOperand("__kq_farcall_pointer_bank0", AddressMode.Absolute));
                RecordCallEdge(expr, "<indirect-far>", -1, "farcall_pointer", viaThunk: true,
                    viaFarcall: true, actualArgSizes: new int[0], expectedArgSizes: new int[0]);
                return;
            }

Read a little-endian 16-bit value at addr and addr+1 under a temporary bank selection, then restore the bank. This is the intrinsic used by far_data_read16.

Syntax

u16 __farpeek16(u8 bank, const void* addr);

Parameters

bank

An unsigned 8-bit ROM-bank number. For a call, it must agree with the function's placement; for a read, it selects the source mapping. Use the target cartridge's valid range.

addr

Near pointer to readable source bytes in the selected ROM bank. It does not contain a bank number.

Return value

The little-endian word read, as u16 (0–65535).

Conditions and limits

The complete byte or word must be readable in the selected CPU mapping. These reads do not validate pointers, clip addresses or advance automatically to another ROM bank at a window boundary. A word read needs two valid consecutive bytes.

Far reads and copies are synchronous and use shared compiler scratch. Do not let an interrupt run another banked transfer over the same scratch while one is active. On GB, the copy helper also uses one shared HRAM slot for the saved bank. The sample performs these operations from fixed code with no competing banked-transfer handler.

These GB bank interfaces carry eight bank bits and do not set the ninth MBC5 bank bit. Cartridge rules still apply, including mapper-specific treatment of bank zero. The example explicitly uses MBC5 banks 1–3; do not mix this state with untracked raw mapper writes.

Usage example

bank_expect(__farpeek16(3,payload+1)==0x5C7A,14);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This excerpt uses __farpeek16 to read payload+1 in bank 3 and checks 5C7A. In the full program, the near read from home2 also confirms that the bank-2 mapping is restored.

The complete program teaches how a bank number and near address identify data, how callbacks cross banks, and how to distinguish the library's record from the actual mapping. All displayed numbers are hexadecimal. BANK IN and BANK OUT must show 02, BYTE HEX D3, WORD HEX 5C7A, and both FAILED CHECKS and FIRST FAILURE 00. CGB and FC display blue text; DMG displays black text.

CALL COUNT is 03: far_call, __farcall and __farcall_ptr each invoke the callback once.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\banked_data_calls.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

if (funcName == "__farpeek16")
            {
                if (args.Length != 2) Error(expr, "__farpeek16(bank, addr) expects 2 arguments");

                CompileIntoA(args[0]); EmitPushAAsWord(); // bank
                CompileIntoHL(args[1]); EmitAsm("PUSH_HL"); // src
                EmitAsm("ADD_SP_IMM", new AsmOperand(-2, AddressMode.Relative)); // scratch
                // At SP: scratch, saved address, saved bank; each occupies two bytes.

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(0, AddressMode.Relative));
                EmitAsm("PUSH_HL"); // dst = &scratch

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                EmitAsm("LD_A_HL");
                EmitAsm("LD_E_A");
                EmitAsm("INC_HL");
                EmitAsm("LD_A_HL");
                EmitAsm("LD_D_A");

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(6, AddressMode.Relative));
                EmitAsm("LD_A_HL"); // bank

                EmitAsm("POP_HL"); // dst
                EmitAsm("LD_BC_IMM", new AsmOperand(2, AddressMode.Immediate16));
                EmitCallFarMemcpyHelper();

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(0, AddressMode.Relative));
                EmitAsm("LD_A_HL");
                EmitAsm("LD_E_A");
                EmitAsm("INC_HL");
                EmitAsm("LD_A_HL");
                EmitAsm("LD_D_A");
                EmitAsm("LD_H_D");
                EmitAsm("LD_L_E");
                EmitAsm("ADD_SP_IMM", new AsmOperand(6, AddressMode.Relative));
                LastCallReturnsHL = true;
                return;
            }

Temporarily select the supplied bank, read one byte at the CPU address and restore the previous bank. This is the intrinsic used by far_data_read8.

Syntax

u8 __farpeek8(u8 bank, const void* addr);

Parameters

bank

An unsigned 8-bit ROM-bank number. For a call, it must agree with the function's placement; for a read, it selects the source mapping. Use the target cartridge's valid range.

addr

Near pointer to readable source bytes in the selected ROM bank. It does not contain a bank number.

Return value

The byte read, as u8 (0–255).

Conditions and limits

The complete byte or word must be readable in the selected CPU mapping. These reads do not validate pointers, clip addresses or advance automatically to another ROM bank at a window boundary. A word read needs two valid consecutive bytes.

Far reads and copies are synchronous and use shared compiler scratch. Do not let an interrupt run another banked transfer over the same scratch while one is active. On GB, the copy helper also uses one shared HRAM slot for the saved bank. The sample performs these operations from fixed code with no competing banked-transfer handler.

These GB bank interfaces carry eight bank bits and do not set the ninth MBC5 bank bit. Cartridge rules still apply, including mapper-specific treatment of bank zero. The example explicitly uses MBC5 banks 1–3; do not mix this state with untracked raw mapper writes.

Usage example

bank_expect(__farpeek8(3,payload)==0xD3,13);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This excerpt uses __farpeek8 to read payload in bank 3 and checks D3. In the full program, the near read from home2 also confirms that the bank-2 mapping is restored.

The complete program teaches how a bank number and near address identify data, how callbacks cross banks, and how to distinguish the library's record from the actual mapping. All displayed numbers are hexadecimal. BANK IN and BANK OUT must show 02, BYTE HEX D3, WORD HEX 5C7A, and both FAILED CHECKS and FIRST FAILURE 00. CGB and FC display blue text; DMG displays black text.

CALL COUNT is 03: far_call, __farcall and __farcall_ptr each invoke the callback once.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\banked_data_calls.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

if (funcName == "__farpeek8")
            {
                if (args.Length != 2) Error(expr, "__farpeek8(bank, addr) expects 2 arguments");

                CompileIntoA(args[0]); EmitPushAAsWord(); // bank
                CompileIntoHL(args[1]); EmitAsm("PUSH_HL"); // src
                EmitAsm("ADD_SP_IMM", new AsmOperand(-2, AddressMode.Relative)); // scratch
                // At SP: scratch, saved address, saved bank; each occupies two bytes.

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(0, AddressMode.Relative));
                EmitAsm("PUSH_HL"); // dst = &scratch

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                EmitAsm("LD_A_HL");
                EmitAsm("LD_E_A");
                EmitAsm("INC_HL");
                EmitAsm("LD_A_HL");
                EmitAsm("LD_D_A");

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(6, AddressMode.Relative));
                EmitAsm("LD_A_HL"); // bank

                EmitAsm("POP_HL"); // dst
                EmitAsm("LD_BC_IMM", new AsmOperand(1, AddressMode.Immediate16));
                EmitCallFarMemcpyHelper();

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(0, AddressMode.Relative));
                EmitAsm("LD_A_HL");
                EmitAsm("ADD_SP_IMM", new AsmOperand(6, AddressMode.Relative));
                return;
            }

Return the compiler's CGB-mode Boolean. An explicit --cgb=dmg target folds to 0 and --cgb=cgb_only to 1; a dual-mode --cgb=cgb target uses the runtime detector. This reports the selected execution mode, not every physical model feature.

Syntax

u8 __cgb_is_cgb();

Return value

u8: 0 for DMG mode, 1 for CGB mode.

Usage example

color_mode=__cgb_is_cgb(); // 0 in DMG mode, 1 in CGB mode for this dual-mode ROM.
if (color_mode>1) failures++;

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This program teaches how palette contents affect the same tile pattern differently in BG and OBJ. Each triangle is 8 × 8 pixels; its top row has one pixel on the left, expanding to a full bottom row. At x = 16, 32, 48, 64, 80, 96, 112, the BG row at y = 24 is red, blue, green, red, blue, green, red. The OBJ row at y = 64 is blue, green, red, blue, green, red, blue. The columns use single-color, component, indexed-range, full-palette, absolute-range, canonical-register and alias-register writes, respectively.

At y = 88, the seven 8 × 8 cells show: red triangle (x = 16), blue one-pixel square outline from bank 1 (32), horizontally reflected green triangle (48), vertically reflected red triangle (64), blue triangle reflected both ways (80), green triangle over a red sprite with red visible through color-zero pixels (96), and a full red sprite in front of the BG triangle as a priority control (112). Coordinates are screen pixels measured from the upper-left corner. Blank space and black text remain on white.

FAILED CHECKS 000 confirms RGB masking, truth-valued flags (including input 2), palette index wrapping, writes crossing a palette boundary, clamping at slot 31, null/zero-length no-ops and palette readback while LCD is off. Four target/hardware combinations are tested: dual-mode ROM on DMG and CGB, DMG-only on DMG, and CGB-only on CGB. On DMG, CGB MODE is 0, all triangles are black, the bank/flip attributes have no display effect, and the last two bottom cells are black squares. CGB MODE is 1 in CGB tests. Real hardware and LCD-on palette contention are not covered.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Safe here means CGB hardware gating. Palette data writes still require an accessible
PPU phase (for example LCD off or a sufficiently short VBlank update).

Write one byte to the background/window palette data register BCPD/BGPD at $FF69 on CGB. __cgb_safe_set_bgpd is another name for the same register. The associated index register selects the byte position; a full RGB15 color requires a low byte and a high byte.

Syntax

void __cgb_safe_set_bcpd(u8 value);

Parameters

value

One byte, 0–255. Write the low byte followed by the high byte of RGB15; enable index auto-increment first, or explicitly select each position. A data write does not enable auto-increment itself.

Return value

None (void).

Conditions and limits

Palette and guarded register writes do nothing in DMG mode. Here, safe means a CGB-mode guard, not a PPU access wait or a critical section. Use LCD-off setup or a sufficiently short update in an accessible PPU phase. These functions do not wait for VBlank or protect a multi-byte update from interrupts.

Usage example

__cgb_safe_set_bcpd(0xE0); __cgb_safe_set_bcpd(0x03); // Green word 0x03E0, low then high.
expect_color(0,27,992);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This program teaches how palette contents affect the same tile pattern differently in BG and OBJ. Each triangle is 8 × 8 pixels; its top row has one pixel on the left, expanding to a full bottom row. At x = 16, 32, 48, 64, 80, 96, 112, the BG row at y = 24 is red, blue, green, red, blue, green, red. The OBJ row at y = 64 is blue, green, red, blue, green, red, blue. The columns use single-color, component, indexed-range, full-palette, absolute-range, canonical-register and alias-register writes, respectively.

At y = 88, the seven 8 × 8 cells show: red triangle (x = 16), blue one-pixel square outline from bank 1 (32), horizontally reflected green triangle (48), vertically reflected red triangle (64), blue triangle reflected both ways (80), green triangle over a red sprite with red visible through color-zero pixels (96), and a full red sprite in front of the BG triangle as a priority control (112). Coordinates are screen pixels measured from the upper-left corner. Blank space and black text remain on white.

FAILED CHECKS 000 confirms RGB masking, truth-valued flags (including input 2), palette index wrapping, writes crossing a palette boundary, clamping at slot 31, null/zero-length no-ops and palette readback while LCD is off. Four target/hardware combinations are tested: dual-mode ROM on DMG and CGB, DMG-only on DMG, and CGB-only on CGB. On DMG, CGB MODE is 0, all triangles are black, the bank/flip attributes have no display effect, and the last two bottom cells are black squares. CGB MODE is 1 in CGB tests. Real hardware and LCD-on palette contention are not covered.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Write the background/window palette byte-index register BCPS/BGPI at $FF68 on CGB. __cgb_safe_set_bgpi writes the same register. This selects where a subsequent data-register access goes; it does not itself write a color.

Syntax

void __cgb_safe_set_bcps(u8 value);

Parameters

value

Byte index in bits 0–5 (0–63), with bit 7 set for auto-increment after data writes; bit 6 is unused. Color slot n starts at byte 2n. Auto-increment wraps after byte 63, so raw register writes require your own range control.

Return value

None (void).

Conditions and limits

Palette and guarded register writes do nothing in DMG mode. Here, safe means a CGB-mode guard, not a PPU access wait or a critical section. Use LCD-off setup or a sufficiently short update in an accessible PPU phase. These functions do not wait for VBlank or protect a multi-byte update from interrupts.

Usage example

__cgb_safe_set_bcps(0xB6); // BG byte 54, with auto-increment enabled (slot 27 low byte).

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This program teaches how palette contents affect the same tile pattern differently in BG and OBJ. Each triangle is 8 × 8 pixels; its top row has one pixel on the left, expanding to a full bottom row. At x = 16, 32, 48, 64, 80, 96, 112, the BG row at y = 24 is red, blue, green, red, blue, green, red. The OBJ row at y = 64 is blue, green, red, blue, green, red, blue. The columns use single-color, component, indexed-range, full-palette, absolute-range, canonical-register and alias-register writes, respectively.

At y = 88, the seven 8 × 8 cells show: red triangle (x = 16), blue one-pixel square outline from bank 1 (32), horizontally reflected green triangle (48), vertically reflected red triangle (64), blue triangle reflected both ways (80), green triangle over a red sprite with red visible through color-zero pixels (96), and a full red sprite in front of the BG triangle as a priority control (112). Coordinates are screen pixels measured from the upper-left corner. Blank space and black text remain on white.

FAILED CHECKS 000 confirms RGB masking, truth-valued flags (including input 2), palette index wrapping, writes crossing a palette boundary, clamping at slot 31, null/zero-length no-ops and palette readback while LCD is off. Four target/hardware combinations are tested: dual-mode ROM on DMG and CGB, DMG-only on DMG, and CGB-only on CGB. On DMG, CGB MODE is 0, all triangles are black, the bank/flip attributes have no display effect, and the last two bottom cells are black squares. CGB MODE is 1 in CGB tests. Real hardware and LCD-on palette contention are not covered.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Write one byte to the sprite (OBJ) palette data register OCPD/OBPD at $FF6B on CGB. __cgb_safe_set_obpd is another name for the same register. The associated index register selects the byte position; a full RGB15 color requires a low byte and a high byte.

Syntax

void __cgb_safe_set_ocpd(u8 value);

Parameters

value

One byte, 0–255. Write the low byte followed by the high byte of RGB15; enable index auto-increment first, or explicitly select each position. A data write does not enable auto-increment itself.

Return value

None (void).

Conditions and limits

Palette and guarded register writes do nothing in DMG mode. Here, safe means a CGB-mode guard, not a PPU access wait or a critical section. Use LCD-off setup or a sufficiently short update in an accessible PPU phase. These functions do not wait for VBlank or protect a multi-byte update from interrupts.

Usage example

__cgb_safe_set_ocpd(31); __cgb_safe_set_ocpd(0); // Red sprite color.
expect_color(1,27,31);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This program teaches how palette contents affect the same tile pattern differently in BG and OBJ. Each triangle is 8 × 8 pixels; its top row has one pixel on the left, expanding to a full bottom row. At x = 16, 32, 48, 64, 80, 96, 112, the BG row at y = 24 is red, blue, green, red, blue, green, red. The OBJ row at y = 64 is blue, green, red, blue, green, red, blue. The columns use single-color, component, indexed-range, full-palette, absolute-range, canonical-register and alias-register writes, respectively.

At y = 88, the seven 8 × 8 cells show: red triangle (x = 16), blue one-pixel square outline from bank 1 (32), horizontally reflected green triangle (48), vertically reflected red triangle (64), blue triangle reflected both ways (80), green triangle over a red sprite with red visible through color-zero pixels (96), and a full red sprite in front of the BG triangle as a priority control (112). Coordinates are screen pixels measured from the upper-left corner. Blank space and black text remain on white.

FAILED CHECKS 000 confirms RGB masking, truth-valued flags (including input 2), palette index wrapping, writes crossing a palette boundary, clamping at slot 31, null/zero-length no-ops and palette readback while LCD is off. Four target/hardware combinations are tested: dual-mode ROM on DMG and CGB, DMG-only on DMG, and CGB-only on CGB. On DMG, CGB MODE is 0, all triangles are black, the bank/flip attributes have no display effect, and the last two bottom cells are black squares. CGB MODE is 1 in CGB tests. Real hardware and LCD-on palette contention are not covered.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Write the sprite (OBJ) palette byte-index register OCPS/OBPI at $FF6A on CGB. __cgb_safe_set_obpi writes the same register. This selects where a subsequent data-register access goes; it does not itself write a color.

Syntax

void __cgb_safe_set_ocps(u8 value);

Parameters

value

Byte index in bits 0–5 (0–63), with bit 7 set for auto-increment after data writes; bit 6 is unused. Color slot n starts at byte 2n. Auto-increment wraps after byte 63, so raw register writes require your own range control.

Return value

None (void).

Conditions and limits

Palette and guarded register writes do nothing in DMG mode. Here, safe means a CGB-mode guard, not a PPU access wait or a critical section. Use LCD-off setup or a sufficiently short update in an accessible PPU phase. These functions do not wait for VBlank or protect a multi-byte update from interrupts.

Usage example

__cgb_safe_set_ocps(0xB6); // OBJ byte 54; this does not select a BG color.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This program teaches how palette contents affect the same tile pattern differently in BG and OBJ. Each triangle is 8 × 8 pixels; its top row has one pixel on the left, expanding to a full bottom row. At x = 16, 32, 48, 64, 80, 96, 112, the BG row at y = 24 is red, blue, green, red, blue, green, red. The OBJ row at y = 64 is blue, green, red, blue, green, red, blue. The columns use single-color, component, indexed-range, full-palette, absolute-range, canonical-register and alias-register writes, respectively.

At y = 88, the seven 8 × 8 cells show: red triangle (x = 16), blue one-pixel square outline from bank 1 (32), horizontally reflected green triangle (48), vertically reflected red triangle (64), blue triangle reflected both ways (80), green triangle over a red sprite with red visible through color-zero pixels (96), and a full red sprite in front of the BG triangle as a priority control (112). Coordinates are screen pixels measured from the upper-left corner. Blank space and black text remain on white.

FAILED CHECKS 000 confirms RGB masking, truth-valued flags (including input 2), palette index wrapping, writes crossing a palette boundary, clamping at slot 31, null/zero-length no-ops and palette readback while LCD is off. Four target/hardware combinations are tested: dual-mode ROM on DMG and CGB, DMG-only on DMG, and CGB-only on CGB. On DMG, CGB MODE is 0, all triangles are black, the bank/flip attributes have no display effect, and the last two bottom cells are black squares. CGB MODE is 1 in CGB tests. Real hardware and LCD-on palette contention are not covered.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Select the CPU's VRAM bank through VBK ($FF4F) on CGB. Only value & 1 is written: even values select bank 0, odd values bank 1. This affects CPU accesses in $8000–$9FFF, not the tile-data bank selected by a map attribute. It does not restore the previous bank.

Syntax

void __cgb_safe_set_vbk(u8 value);

Parameters

value

Select the CPU's VRAM bank through VBK ($FF4F) on CGB. Only value & 1 is written: even values select bank 0, odd values bank 1. This affects CPU accesses in $8000–$9FFF, not the tile-data bank selected by a map attribute. It does not restore the previous bank.

Return value

None (void).

Conditions and limits

Palette and guarded register writes do nothing in DMG mode. Here, safe means a CGB-mode guard, not a PPU access wait or a critical section. Use LCD-off setup or a sufficiently short update in an accessible PPU phase. These functions do not wait for VBlank or protect a multi-byte update from interrupts.

Usage example

if (color_mode) {
    __cgb_safe_set_vbk(3); // Only bit zero is kept: CPU accesses now use bank 1.
    if ((P_VBK&1)!=1) failures++;
    __vram_copy(0x8010,shape1,16);
    __cgb_safe_set_vbk(2); // Bit zero is clear, so return to bank 0.
    if ((P_VBK&1)!=0) failures++;
}

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This program teaches how palette contents affect the same tile pattern differently in BG and OBJ. Each triangle is 8 × 8 pixels; its top row has one pixel on the left, expanding to a full bottom row. At x = 16, 32, 48, 64, 80, 96, 112, the BG row at y = 24 is red, blue, green, red, blue, green, red. The OBJ row at y = 64 is blue, green, red, blue, green, red, blue. The columns use single-color, component, indexed-range, full-palette, absolute-range, canonical-register and alias-register writes, respectively.

At y = 88, the seven 8 × 8 cells show: red triangle (x = 16), blue one-pixel square outline from bank 1 (32), horizontally reflected green triangle (48), vertically reflected red triangle (64), blue triangle reflected both ways (80), green triangle over a red sprite with red visible through color-zero pixels (96), and a full red sprite in front of the BG triangle as a priority control (112). Coordinates are screen pixels measured from the upper-left corner. Blank space and black text remain on white.

FAILED CHECKS 000 confirms RGB masking, truth-valued flags (including input 2), palette index wrapping, writes crossing a palette boundary, clamping at slot 31, null/zero-length no-ops and palette readback while LCD is off. Four target/hardware combinations are tested: dual-mode ROM on DMG and CGB, DMG-only on DMG, and CGB-only on CGB. On DMG, CGB MODE is 0, all triangles are black, the bank/flip attributes have no display effect, and the last two bottom cells are black squares. CGB MODE is 1 in CGB tests. Real hardware and LCD-on palette contention are not covered.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Write the VRAM bank selection only on CGB. Safe here means hardware-mode guarded, not PPU-timed.

Write one tile-number byte to the tile map; this selects an existing tile image, not new pixel data.

The destination is always 0x9800 + 32*y + x, regardless of which maps LCDC selects for the background and window.

Waits for writable VRAM when necessary. The LCD-on path uses interrupt masking and can enable interrupts afterward; it is not a promise to preserve the caller's interrupt state or to finish within one VBlank.

Syntax

void __settile(u8 x, u8 y, u8 tile);

Parameters

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

tile

Tile number, 0–255. LCDC bit 4 determines how the number addresses tile-image data. It is not a VRAM byte address.

Return value

None (void).

Conditions and limits

Tile bytes go to the currently selected VRAM bank. On CGB, select bank 0 for tile numbers; this call does not switch banks for you.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settile
// Write one tile-number byte to the tile map; this selects an existing tile image, not
// new pixel data. The destination is always `0x9800 + 32*y + x`, regardless of which
// maps LCDC selects for the background and window.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_color_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_color_example_begin();
    __settile(2, 3, 'A');
    if (tile_example_read(0x9862, 0) != 'A') { failures++; }
    if (tile_example_read(0x9C62, 0) != 0) { failures++; }
    tile_example_finish(failures, 0);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB, the sample characters and status text are blue on white. The setup gives palette 0 a blue ink color; it does not change the tile-map attributes. On DMG, the same characters are black on white.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settile.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settile.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Write a tile number to map 9800, waiting for VRAM access when necessary.

Copy count consecutive tile-number bytes from src to the VRAM byte address dest. The count is in bytes, not tile-image units; no row-stride adjustment is made.

Waits for writable VRAM when necessary. The LCD-on path uses interrupt masking and can enable interrupts afterward; it is not a promise to preserve the caller's interrupt state or to finish within one VBlank.

Syntax

void __settile_bulk(u16 dest, const u8* src, u8 count);

Parameters

dest

First VRAM byte address. For a map, use an address in 0x9800–0x9FFF and keep the full transfer within the intended map.

src

Packed source bytes in RAM or a visible ROM bank. A tile stream contains tile numbers; an attribute stream contains CGB attribute bytes. The routine copies now and does not retain the pointer.

count

Number of bytes, 0–255. Zero copies nothing. Supply at least this many readable source bytes.

Return value

None (void).

Conditions and limits

Tile bytes go to the currently selected VRAM bank. On CGB, select bank 0 for tile numbers; this call does not switch banks for you.

Keep each source buffer readable and its ROM bank visible throughout the copy. Return type: void.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settile_bulk
// Copy `count` consecutive tile-number bytes from `src` to the VRAM byte address `dest`.
// The count is in bytes, not tile-image units; no row-stride adjustment is made. Waits
// for writable VRAM when necessary. The LCD-on path uses interrupt masking and can
// enable interrupts afterward; it is not a promise to preserve the caller's interrupt
// state or to finish within one VBlank.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_color_example.h"
const u8 example_tiles[] = {'A','B','C'};
const u8 example_attrs[] = {1,2,3};

void main() {
    u8 failures;
    failures = 0;
    tile_color_example_begin();
    __settile_bulk(0x9862, example_tiles, 3);
    if (tile_example_read(0x9862, 0) != 'A') { failures++; }
    if (tile_example_read(0x9863, 0) != 'B') { failures++; }
    if (tile_example_read(0x9864, 0) != 'C') { failures++; }
    if (tile_example_read(0x9865, 0) != 0) { failures++; }
    tile_example_finish(failures, 0);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB, the sample characters and status text are blue on white. The setup gives palette 0 a blue ink color; it does not change the tile-map attributes. On DMG, the same characters are black on white.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

ABC

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settile_bulk.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settile_bulk.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Copy count sequential bytes to dest using the current VRAM bank and access-checked transfer.

Copy count consecutive tile-number bytes from src to the VRAM byte address dest. The count is in bytes, not tile-image units; no row-stride adjustment is made.

Does not wait for VRAM access. Call only while the LCD is off or within a caller-managed writable interval with enough time for the whole transfer.

Syntax

void __settile_bulk_fast(u16 dest, const u8* src, u8 count);

Parameters

dest

First VRAM byte address. For a map, use an address in 0x9800–0x9FFF and keep the full transfer within the intended map.

src

Packed source bytes in RAM or a visible ROM bank. A tile stream contains tile numbers; an attribute stream contains CGB attribute bytes. The routine copies now and does not retain the pointer.

count

Number of bytes, 0–255. Zero copies nothing. Supply at least this many readable source bytes.

Return value

None (void).

Conditions and limits

Tile bytes go to the currently selected VRAM bank. On CGB, select bank 0 for tile numbers; this call does not switch banks for you.

Keep each source buffer readable and its ROM bank visible throughout the copy. Return type: void.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settile_bulk_fast
// Copy `count` consecutive tile-number bytes from `src` to the VRAM byte address `dest`.
// The count is in bytes, not tile-image units; no row-stride adjustment is made. Does
// not wait for VRAM access. Call only while the LCD is off or within a caller-managed
// writable interval with enough time for the whole transfer.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_color_example.h"
const u8 example_tiles[] = {'A','B','C'};
const u8 example_attrs[] = {1,2,3};

void main() {
    u8 failures;
    failures = 0;
    tile_color_example_begin();
    __settile_bulk_fast(0x9862, example_tiles, 3);
    if (tile_example_read(0x9862, 0) != 'A') { failures++; }
    if (tile_example_read(0x9863, 0) != 'B') { failures++; }
    if (tile_example_read(0x9864, 0) != 'C') { failures++; }
    if (tile_example_read(0x9865, 0) != 0) { failures++; }
    tile_example_finish(failures, 0);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB, the sample characters and status text are blue on white. The setup gives palette 0 a blue ink color; it does not change the tile-map attributes. On DMG, the same characters are black on white.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

ABC

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settile_bulk_fast.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settile_bulk_fast.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Copy count sequential bytes to dest without VRAM access waits; retain source-bank visibility.

Write one tile-number byte to the tile map; this selects an existing tile image, not new pixel data.

The destination is always 0x9800 + 32*y + x, regardless of which maps LCDC selects for the background and window.

Does not wait for VRAM access. Call only while the LCD is off or within a caller-managed writable interval with enough time for the whole transfer.

Syntax

void __settile_unsafe(u8 x, u8 y, u8 tile);

Parameters

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

tile

Tile number, 0–255. LCDC bit 4 determines how the number addresses tile-image data. It is not a VRAM byte address.

Return value

None (void).

Conditions and limits

Tile bytes go to the currently selected VRAM bank. On CGB, select bank 0 for tile numbers; this call does not switch banks for you.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settile_unsafe
// Write one tile-number byte to the tile map; this selects an existing tile image, not
// new pixel data. The destination is always `0x9800 + 32*y + x`, regardless of which
// maps LCDC selects for the background and window.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_color_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_color_example_begin();
    __settile_unsafe(2, 3, 'A');
    if (tile_example_read(0x9862, 0) != 'A') { failures++; }
    if (tile_example_read(0x9C62, 0) != 0) { failures++; }
    tile_example_finish(failures, 0);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB, the sample characters and status text are blue on white. The setup gives palette 0 a blue ink color; it does not change the tile-map attributes. On DMG, the same characters are black on white.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settile_unsafe.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settile_unsafe.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Write a tile number to map 9800 without waiting for writable VRAM.

Write one tile-number byte to the tile map; this selects an existing tile image, not new pixel data.

base explicitly selects the map (0x9800 or 0x9C00); the byte address is base + 32*y + x.

Waits for writable VRAM when necessary. The LCD-on path uses interrupt masking and can enable interrupts afterward; it is not a promise to preserve the caller's interrupt state or to finish within one VBlank.

Syntax

void __settileat(u16 base, u8 x, u8 y, u8 tile);

Parameters

base

base explicitly selects the map (0x9800 or 0x9C00); the byte address is base + 32*y + x.

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

tile

Tile number, 0–255. LCDC bit 4 determines how the number addresses tile-image data. It is not a VRAM byte address.

Return value

None (void).

Conditions and limits

Tile bytes go to the currently selected VRAM bank. On CGB, select bank 0 for tile numbers; this call does not switch banks for you.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settileat
// Write one tile-number byte to the tile map; this selects an existing tile image, not
// new pixel data. `base` explicitly selects the map (`0x9800` or `0x9C00`); the byte
// address is `base + 32*y + x`.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_color_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_color_example_begin();
    __settileat(0x9C00, 2, 3, 'A');
    if (tile_example_read(0x9C62, 0) != 'A') { failures++; }
    if (tile_example_read(0x9862, 0) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB, the sample characters and status text are blue on white. The setup gives palette 0 a blue ink color; it does not change the tile-map attributes. On DMG, the same characters are black on white.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settileat.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settileat.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Write at base+32*y+x with VRAM access checks; supply a valid tile-map base.

Write one tile-number byte to the tile map; this selects an existing tile image, not new pixel data.

base explicitly selects the map (0x9800 or 0x9C00); the byte address is base + 32*y + x.

Does not wait for VRAM access. Call only while the LCD is off or within a caller-managed writable interval with enough time for the whole transfer.

Syntax

void __settileat_unsafe(u16 base, u8 x, u8 y, u8 tile);

Parameters

base

base explicitly selects the map (0x9800 or 0x9C00); the byte address is base + 32*y + x.

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

tile

Tile number, 0–255. LCDC bit 4 determines how the number addresses tile-image data. It is not a VRAM byte address.

Return value

None (void).

Conditions and limits

Tile bytes go to the currently selected VRAM bank. On CGB, select bank 0 for tile numbers; this call does not switch banks for you.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settileat_unsafe
// Write one tile-number byte to the tile map; this selects an existing tile image, not
// new pixel data. `base` explicitly selects the map (`0x9800` or `0x9C00`); the byte
// address is `base + 32*y + x`.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_color_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_color_example_begin();
    __settileat_unsafe(0x9C00, 2, 3, 'A');
    if (tile_example_read(0x9C62, 0) != 'A') { failures++; }
    if (tile_example_read(0x9862, 0) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB, the sample characters and status text are blue on white. The setup gives palette 0 a blue ink color; it does not change the tile-map attributes. On DMG, the same characters are black on white.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settileat_unsafe.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settileat_unsafe.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Use an explicit map base without waiting for VRAM access.

Write only the CGB attribute byte; leave the tile number unchanged. Attribute bits select palette, tile-data bank, flips and priority.

base explicitly selects the map (0x9800 or 0x9C00); the byte address is base + 32*y + x.

Waits for writable VRAM when necessary. The LCD-on path uses interrupt masking and can enable interrupts afterward; it is not a promise to preserve the caller's interrupt state or to finish within one VBlank.

Syntax

void __settileatattr(u16 base, u8 x, u8 y, u8 attr);

Parameters

base

base explicitly selects the map (0x9800 or 0x9C00); the byte address is base + 32*y + x.

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

attr

CGB attribute byte: bits 0–2 select palette 0–7; bit 3 selects tile-data bank; bits 5 and 6 flip horizontally and vertically; bit 7 sets BG/window priority. Keep unused bit 4 zero.

Return value

None (void).

Conditions and limits

On CGB, temporarily selects VRAM bank 1 and leaves VBK=0 afterward. On DMG, no attribute write occurs.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settileatattr
// Write only the CGB attribute byte; leave the tile number unchanged. Attribute bits
// select palette, tile-data bank, flips and priority. `base` explicitly selects the map
// (`0x9800` or `0x9C00`); the byte address is `base + 32*y + x`.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settileat(0x9C00, 2, 3, 'A');
    __settileatattr(0x9C00, 2, 3, KQ_CGB_ATTR(2, 0, 0, 0, 0));
    if (tile_example_read(0x9C62, 0) != 'A') { failures++; }
    if (tile_example_read(0x9862, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C62, 1) != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB the A is blue: attribute value 2 selects the blue palette prepared by this example. On DMG the same character is black because CGB attributes are not applied.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settileatattr.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settileatattr.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Write attributes in bank one at the explicit map base on CGB, then leave VBK zero; skip on DMG. Use the access-checked write path.

Write only the CGB attribute byte; leave the tile number unchanged. Attribute bits select palette, tile-data bank, flips and priority.

base explicitly selects the map (0x9800 or 0x9C00); the byte address is base + 32*y + x.

Does not wait for VRAM access. Call only while the LCD is off or within a caller-managed writable interval with enough time for the whole transfer.

Syntax

void __settileatattr_unsafe(u16 base, u8 x, u8 y, u8 attr);

Parameters

base

base explicitly selects the map (0x9800 or 0x9C00); the byte address is base + 32*y + x.

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

attr

CGB attribute byte: bits 0–2 select palette 0–7; bit 3 selects tile-data bank; bits 5 and 6 flip horizontally and vertically; bit 7 sets BG/window priority. Keep unused bit 4 zero.

Return value

None (void).

Conditions and limits

On CGB, temporarily selects VRAM bank 1 and leaves VBK=0 afterward. On DMG, no attribute write occurs.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settileatattr_unsafe
// Write only the CGB attribute byte; leave the tile number unchanged. Attribute bits
// select palette, tile-data bank, flips and priority. `base` explicitly selects the map
// (`0x9800` or `0x9C00`); the byte address is `base + 32*y + x`.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settileat(0x9C00, 2, 3, 'A');
    __settileatattr_unsafe(0x9C00, 2, 3, KQ_CGB_ATTR(2, 0, 0, 0, 0));
    if (tile_example_read(0x9C62, 0) != 'A') { failures++; }
    if (tile_example_read(0x9862, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C62, 1) != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB the A is blue: attribute value 2 selects the blue palette prepared by this example. On DMG the same character is black because CGB attributes are not applied.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settileatattr_unsafe.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settileatattr_unsafe.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Write attributes in bank one at the explicit map base on CGB, then leave VBK zero; skip on DMG. No VRAM access waits are inserted.

Write a tile number and its CGB attribute. On DMG, only the tile-number write is performed. On CGB, enter with VRAM bank 0 selected; attributes use bank 1 and the call finishes with VBK=0.

base explicitly selects the map (0x9800 or 0x9C00); the byte address is base + 32*y + x.

Waits for writable VRAM when necessary. The LCD-on path uses interrupt masking and can enable interrupts afterward; it is not a promise to preserve the caller's interrupt state or to finish within one VBlank.

Syntax

void __settileatcgb(u16 base, u8 x, u8 y, u8 tile, u8 attr);

Parameters

base

base explicitly selects the map (0x9800 or 0x9C00); the byte address is base + 32*y + x.

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

tile

Tile number, 0–255. LCDC bit 4 determines how the number addresses tile-image data. It is not a VRAM byte address.

attr

CGB attribute byte: bits 0–2 select palette 0–7; bit 3 selects tile-data bank; bits 5 and 6 flip horizontally and vertically; bit 7 sets BG/window priority. Keep unused bit 4 zero.

Return value

None (void).

Conditions and limits

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settileatcgb
// Write a tile number and its CGB attribute. On DMG, only the tile-number write is
// performed. On CGB, enter with VRAM bank 0 selected; attributes use bank 1 and the call
// finishes with `VBK=0`. `base` explicitly selects the map (`0x9800` or `0x9C00`); the
// byte address is `base + 32*y + x`.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settileatcgb(0x9C00, 2, 3, 'A', KQ_CGB_ATTR(2, 0, 0, 0, 0));
    if (tile_example_read(0x9C62, 0) != 'A') { failures++; }
    if (tile_example_read(0x9862, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C62, 1) != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB the A is blue: attribute value 2 selects the blue palette prepared by this example. On DMG the same character is black because CGB attributes are not applied.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settileatcgb.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settileatcgb.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Write tile and CGB attributes at the explicit map base; DMG receives only the tile write. Use the access-checked write path.

Write a tile number and its CGB attribute. On DMG, only the tile-number write is performed. On CGB, enter with VRAM bank 0 selected; attributes use bank 1 and the call finishes with VBK=0.

base explicitly selects the map (0x9800 or 0x9C00); the byte address is base + 32*y + x.

Does not wait for VRAM access. Call only while the LCD is off or within a caller-managed writable interval with enough time for the whole transfer.

Syntax

void __settileatcgb_unsafe(u16 base, u8 x, u8 y, u8 tile, u8 attr);

Parameters

base

base explicitly selects the map (0x9800 or 0x9C00); the byte address is base + 32*y + x.

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

tile

Tile number, 0–255. LCDC bit 4 determines how the number addresses tile-image data. It is not a VRAM byte address.

attr

CGB attribute byte: bits 0–2 select palette 0–7; bit 3 selects tile-data bank; bits 5 and 6 flip horizontally and vertically; bit 7 sets BG/window priority. Keep unused bit 4 zero.

Return value

None (void).

Conditions and limits

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settileatcgb_unsafe
// Write a tile number and its CGB attribute. On DMG, only the tile-number write is
// performed. On CGB, enter with VRAM bank 0 selected; attributes use bank 1 and the call
// finishes with `VBK=0`. `base` explicitly selects the map (`0x9800` or `0x9C00`); the
// byte address is `base + 32*y + x`.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settileatcgb_unsafe(0x9C00, 2, 3, 'A', KQ_CGB_ATTR(2, 0, 0, 0, 0));
    if (tile_example_read(0x9C62, 0) != 'A') { failures++; }
    if (tile_example_read(0x9862, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C62, 1) != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB the A is blue: attribute value 2 selects the blue palette prepared by this example. On DMG the same character is black because CGB attributes are not applied.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settileatcgb_unsafe.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settileatcgb_unsafe.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Write tile and CGB attributes at the explicit map base; DMG receives only the tile write. No VRAM access waits are inserted.

Write only the CGB attribute byte; leave the tile number unchanged. Attribute bits select palette, tile-data bank, flips and priority.

The destination is always 0x9800 + 32*y + x, regardless of which maps LCDC selects for the background and window.

Waits for writable VRAM when necessary. The LCD-on path uses interrupt masking and can enable interrupts afterward; it is not a promise to preserve the caller's interrupt state or to finish within one VBlank.

Syntax

void __settileattr(u8 x, u8 y, u8 attr);

Parameters

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

attr

CGB attribute byte: bits 0–2 select palette 0–7; bit 3 selects tile-data bank; bits 5 and 6 flip horizontally and vertically; bit 7 sets BG/window priority. Keep unused bit 4 zero.

Return value

None (void).

Conditions and limits

On CGB, temporarily selects VRAM bank 1 and leaves VBK=0 afterward. On DMG, no attribute write occurs.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settileattr
// Write only the CGB attribute byte; leave the tile number unchanged. Attribute bits
// select palette, tile-data bank, flips and priority. The destination is always `0x9800
// + 32*y + x`, regardless of which maps LCDC selects for the background and window.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settileat(0x9800, 2, 3, 'A');
    __settileattr(2, 3, KQ_CGB_ATTR(2, 0, 0, 0, 0));
    if (tile_example_read(0x9862, 0) != 'A') { failures++; }
    if (tile_example_read(0x9C62, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C62, 1) != 0) { failures++; }
    tile_example_finish(failures, 0);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB the A is blue: attribute value 2 selects the blue palette prepared by this example. On DMG the same character is black because CGB attributes are not applied.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settileattr.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settileattr.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Write attributes in bank one at map 9800 on CGB, then leave VBK zero; skip on DMG. Use the access-checked write path.

Copy count consecutive CGB attribute bytes from src to dest in VRAM bank 1. Tile numbers are untouched; the destination is a byte address, not an (x,y) pair.

Waits for writable VRAM when necessary. The LCD-on path uses interrupt masking and can enable interrupts afterward; it is not a promise to preserve the caller's interrupt state or to finish within one VBlank.

Syntax

void __settileattr_bulk(u16 dest, const u8* src, u8 count);

Parameters

dest

First VRAM byte address. For a map, use an address in 0x9800–0x9FFF and keep the full transfer within the intended map.

src

Packed source bytes in RAM or a visible ROM bank. A tile stream contains tile numbers; an attribute stream contains CGB attribute bytes. The routine copies now and does not retain the pointer.

count

Number of bytes, 0–255. Zero copies nothing. Supply at least this many readable source bytes.

Return value

None (void).

Conditions and limits

On CGB, temporarily selects VRAM bank 1 and leaves VBK=0 afterward. On DMG, no attribute write occurs.

Keep each source buffer readable and its ROM bank visible throughout the copy. Return type: void.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settileattr_bulk
// Copy `count` consecutive CGB attribute bytes from `src` to `dest` in VRAM bank 1. Tile
// numbers are untouched; the destination is a byte address, not an `(x,y)` pair. Waits
// for writable VRAM when necessary. The LCD-on path uses interrupt masking and can
// enable interrupts afterward; it is not a promise to preserve the caller's interrupt
// state or to finish within one VBlank.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"
const u8 example_tiles[] = {'A','B','C'};
const u8 example_attrs[] = {1,2,3};

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settile_bulk(0x9862, example_tiles, 3);
    __settileattr_bulk(0x9862, example_attrs, 3);
    if (tile_example_read(0x9862, 0) != 'A') { failures++; }
    if (tile_example_read(0x9863, 0) != 'B') { failures++; }
    if (tile_example_read(0x9864, 0) != 'C') { failures++; }
    if (tile_example_read(0x9865, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 1) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9864, 1) != 3) { failures++; }
    tile_example_finish(failures, 0);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB, A, B and C are red, blue and green respectively: attribute bytes 1,2,3 select three different prepared palettes. On DMG all three are black.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

ABC

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settileattr_bulk.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settileattr_bulk.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Copy count attributes to dest in bank one on CGB, then leave VBK zero; skip on DMG. Transfers use access checks.

Copy count consecutive CGB attribute bytes from src to dest in VRAM bank 1. Tile numbers are untouched; the destination is a byte address, not an (x,y) pair.

Does not wait for VRAM access. Call only while the LCD is off or within a caller-managed writable interval with enough time for the whole transfer.

Syntax

void __settileattr_bulk_fast(u16 dest, const u8* src, u8 count);

Parameters

dest

First VRAM byte address. For a map, use an address in 0x9800–0x9FFF and keep the full transfer within the intended map.

src

Packed source bytes in RAM or a visible ROM bank. A tile stream contains tile numbers; an attribute stream contains CGB attribute bytes. The routine copies now and does not retain the pointer.

count

Number of bytes, 0–255. Zero copies nothing. Supply at least this many readable source bytes.

Return value

None (void).

Conditions and limits

On CGB, temporarily selects VRAM bank 1 and leaves VBK=0 afterward. On DMG, no attribute write occurs.

Keep each source buffer readable and its ROM bank visible throughout the copy. Return type: void.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settileattr_bulk_fast
// Copy `count` consecutive CGB attribute bytes from `src` to `dest` in VRAM bank 1. Tile
// numbers are untouched; the destination is a byte address, not an `(x,y)` pair. Does
// not wait for VRAM access. Call only while the LCD is off or within a caller-managed
// writable interval with enough time for the whole transfer.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"
const u8 example_tiles[] = {'A','B','C'};
const u8 example_attrs[] = {1,2,3};

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settile_bulk(0x9862, example_tiles, 3);
    __settileattr_bulk_fast(0x9862, example_attrs, 3);
    if (tile_example_read(0x9862, 0) != 'A') { failures++; }
    if (tile_example_read(0x9863, 0) != 'B') { failures++; }
    if (tile_example_read(0x9864, 0) != 'C') { failures++; }
    if (tile_example_read(0x9865, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 1) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9864, 1) != 3) { failures++; }
    tile_example_finish(failures, 0);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB, A, B and C are red, blue and green respectively: attribute bytes 1,2,3 select three different prepared palettes. On DMG all three are black.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

ABC

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settileattr_bulk_fast.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settileattr_bulk_fast.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Copy count attributes to dest in bank one on CGB, then leave VBK zero; skip on DMG. The caller supplies writable VRAM timing.

Write only the CGB attribute byte; leave the tile number unchanged. Attribute bits select palette, tile-data bank, flips and priority.

The destination is always 0x9800 + 32*y + x, regardless of which maps LCDC selects for the background and window.

Does not wait for VRAM access. Call only while the LCD is off or within a caller-managed writable interval with enough time for the whole transfer.

Syntax

void __settileattr_unsafe(u8 x, u8 y, u8 attr);

Parameters

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

attr

CGB attribute byte: bits 0–2 select palette 0–7; bit 3 selects tile-data bank; bits 5 and 6 flip horizontally and vertically; bit 7 sets BG/window priority. Keep unused bit 4 zero.

Return value

None (void).

Conditions and limits

On CGB, temporarily selects VRAM bank 1 and leaves VBK=0 afterward. On DMG, no attribute write occurs.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settileattr_unsafe
// Write only the CGB attribute byte; leave the tile number unchanged. Attribute bits
// select palette, tile-data bank, flips and priority. The destination is always `0x9800
// + 32*y + x`, regardless of which maps LCDC selects for the background and window.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settileat(0x9800, 2, 3, 'A');
    __settileattr_unsafe(2, 3, KQ_CGB_ATTR(2, 0, 0, 0, 0));
    if (tile_example_read(0x9862, 0) != 'A') { failures++; }
    if (tile_example_read(0x9C62, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C62, 1) != 0) { failures++; }
    tile_example_finish(failures, 0);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB the A is blue: attribute value 2 selects the blue palette prepared by this example. On DMG the same character is black because CGB attributes are not applied.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settileattr_unsafe.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settileattr_unsafe.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Write attributes in bank one at map 9800 on CGB, then leave VBK zero; skip on DMG. No VRAM access waits are inserted.

Write one tile-number byte to the tile map; this selects an existing tile image, not new pixel data.

LCDC bit 3 selects the background map: zero uses 0x9800, one uses 0x9C00. The destination is that base plus 32*y + x.

Waits for writable VRAM when necessary. The LCD-on path uses interrupt masking and can enable interrupts afterward; it is not a promise to preserve the caller's interrupt state or to finish within one VBlank.

Syntax

void __settilebg(u8 x, u8 y, u8 tile);

Parameters

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

tile

Tile number, 0–255. LCDC bit 4 determines how the number addresses tile-image data. It is not a VRAM byte address.

Return value

None (void).

Conditions and limits

Tile bytes go to the currently selected VRAM bank. On CGB, select bank 0 for tile numbers; this call does not switch banks for you.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilebg
// Write one tile-number byte to the tile map; this selects an existing tile image, not
// new pixel data. LCDC bit 3 selects the background map: zero uses `0x9800`, one uses
// `0x9C00`. The destination is that base plus `32*y + x`.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_color_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_color_example_begin();
    __settilebg(2, 3, 'A');
    if (tile_example_read(0x9C62, 0) != 'A') { failures++; }
    if (tile_example_read(0x9862, 0) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB, the sample characters and status text are blue on white. The setup gives palette 0 a blue ink color; it does not change the tile-map attributes. On DMG, the same characters are black on white.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilebg.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilebg.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Select the background map from LCDC bit 3, then write with access checks.

Write one tile-number byte to the tile map; this selects an existing tile image, not new pixel data.

LCDC bit 3 selects the background map: zero uses 0x9800, one uses 0x9C00. The destination is that base plus 32*y + x.

Does not wait for VRAM access. Call only while the LCD is off or within a caller-managed writable interval with enough time for the whole transfer.

Syntax

void __settilebg_unsafe(u8 x, u8 y, u8 tile);

Parameters

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

tile

Tile number, 0–255. LCDC bit 4 determines how the number addresses tile-image data. It is not a VRAM byte address.

Return value

None (void).

Conditions and limits

Tile bytes go to the currently selected VRAM bank. On CGB, select bank 0 for tile numbers; this call does not switch banks for you.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilebg_unsafe
// Write one tile-number byte to the tile map; this selects an existing tile image, not
// new pixel data. LCDC bit 3 selects the background map: zero uses `0x9800`, one uses
// `0x9C00`. The destination is that base plus `32*y + x`.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_color_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_color_example_begin();
    __settilebg_unsafe(2, 3, 'A');
    if (tile_example_read(0x9C62, 0) != 'A') { failures++; }
    if (tile_example_read(0x9862, 0) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB, the sample characters and status text are blue on white. The setup gives palette 0 a blue ink color; it does not change the tile-map attributes. On DMG, the same characters are black on white.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilebg_unsafe.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilebg_unsafe.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Select the LCDC background map and write without access waits.

Write only the CGB attribute byte; leave the tile number unchanged. Attribute bits select palette, tile-data bank, flips and priority.

LCDC bit 3 selects the background map: zero uses 0x9800, one uses 0x9C00. The destination is that base plus 32*y + x.

Waits for writable VRAM when necessary. The LCD-on path uses interrupt masking and can enable interrupts afterward; it is not a promise to preserve the caller's interrupt state or to finish within one VBlank.

Syntax

void __settilebgattr(u8 x, u8 y, u8 attr);

Parameters

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

attr

CGB attribute byte: bits 0–2 select palette 0–7; bit 3 selects tile-data bank; bits 5 and 6 flip horizontally and vertically; bit 7 sets BG/window priority. Keep unused bit 4 zero.

Return value

None (void).

Conditions and limits

On CGB, temporarily selects VRAM bank 1 and leaves VBK=0 afterward. On DMG, no attribute write occurs.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilebgattr
// Write only the CGB attribute byte; leave the tile number unchanged. Attribute bits
// select palette, tile-data bank, flips and priority. LCDC bit 3 selects the background
// map: zero uses `0x9800`, one uses `0x9C00`. The destination is that base plus `32*y +
// x`.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settileat(0x9C00, 2, 3, 'A');
    __settilebgattr(2, 3, KQ_CGB_ATTR(2, 0, 0, 0, 0));
    if (tile_example_read(0x9C62, 0) != 'A') { failures++; }
    if (tile_example_read(0x9862, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C62, 1) != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB the A is blue: attribute value 2 selects the blue palette prepared by this example. On DMG the same character is black because CGB attributes are not applied.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilebgattr.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilebgattr.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Write attributes in bank one at the LCDC background map on CGB, then leave VBK zero; skip on DMG. Use the access-checked write path.

Write only the CGB attribute byte; leave the tile number unchanged. Attribute bits select palette, tile-data bank, flips and priority.

LCDC bit 3 selects the background map: zero uses 0x9800, one uses 0x9C00. The destination is that base plus 32*y + x.

Does not wait for VRAM access. Call only while the LCD is off or within a caller-managed writable interval with enough time for the whole transfer.

Syntax

void __settilebgattr_unsafe(u8 x, u8 y, u8 attr);

Parameters

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

attr

CGB attribute byte: bits 0–2 select palette 0–7; bit 3 selects tile-data bank; bits 5 and 6 flip horizontally and vertically; bit 7 sets BG/window priority. Keep unused bit 4 zero.

Return value

None (void).

Conditions and limits

On CGB, temporarily selects VRAM bank 1 and leaves VBK=0 afterward. On DMG, no attribute write occurs.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilebgattr_unsafe
// Write only the CGB attribute byte; leave the tile number unchanged. Attribute bits
// select palette, tile-data bank, flips and priority. LCDC bit 3 selects the background
// map: zero uses `0x9800`, one uses `0x9C00`. The destination is that base plus `32*y +
// x`.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settileat(0x9C00, 2, 3, 'A');
    __settilebgattr_unsafe(2, 3, KQ_CGB_ATTR(2, 0, 0, 0, 0));
    if (tile_example_read(0x9C62, 0) != 'A') { failures++; }
    if (tile_example_read(0x9862, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C62, 1) != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB the A is blue: attribute value 2 selects the blue palette prepared by this example. On DMG the same character is black because CGB attributes are not applied.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilebgattr_unsafe.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilebgattr_unsafe.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Write attributes in bank one at the LCDC background map on CGB, then leave VBK zero; skip on DMG. No VRAM access waits are inserted.

Write a tile number and its CGB attribute. On DMG, only the tile-number write is performed. On CGB, enter with VRAM bank 0 selected; attributes use bank 1 and the call finishes with VBK=0.

LCDC bit 3 selects the background map: zero uses 0x9800, one uses 0x9C00. The destination is that base plus 32*y + x.

Waits for writable VRAM when necessary. The LCD-on path uses interrupt masking and can enable interrupts afterward; it is not a promise to preserve the caller's interrupt state or to finish within one VBlank.

Syntax

void __settilebgcgb(u8 x, u8 y, u8 tile, u8 attr);

Parameters

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

tile

Tile number, 0–255. LCDC bit 4 determines how the number addresses tile-image data. It is not a VRAM byte address.

attr

CGB attribute byte: bits 0–2 select palette 0–7; bit 3 selects tile-data bank; bits 5 and 6 flip horizontally and vertically; bit 7 sets BG/window priority. Keep unused bit 4 zero.

Return value

None (void).

Conditions and limits

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilebgcgb
// Write a tile number and its CGB attribute. On DMG, only the tile-number write is
// performed. On CGB, enter with VRAM bank 0 selected; attributes use bank 1 and the call
// finishes with `VBK=0`. LCDC bit 3 selects the background map: zero uses `0x9800`, one
// uses `0x9C00`. The destination is that base plus `32*y + x`.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settilebgcgb(2, 3, 'A', KQ_CGB_ATTR(2, 0, 0, 0, 0));
    if (tile_example_read(0x9C62, 0) != 'A') { failures++; }
    if (tile_example_read(0x9862, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C62, 1) != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB the A is blue: attribute value 2 selects the blue palette prepared by this example. On DMG the same character is black because CGB attributes are not applied.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilebgcgb.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilebgcgb.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Write tile and CGB attributes at the LCDC background map; DMG receives only the tile write. Use the access-checked write path.

Write a tile number and its CGB attribute. On DMG, only the tile-number write is performed. On CGB, enter with VRAM bank 0 selected; attributes use bank 1 and the call finishes with VBK=0.

LCDC bit 3 selects the background map: zero uses 0x9800, one uses 0x9C00. The destination is that base plus 32*y + x.

Does not wait for VRAM access. Call only while the LCD is off or within a caller-managed writable interval with enough time for the whole transfer.

Syntax

void __settilebgcgb_unsafe(u8 x, u8 y, u8 tile, u8 attr);

Parameters

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

tile

Tile number, 0–255. LCDC bit 4 determines how the number addresses tile-image data. It is not a VRAM byte address.

attr

CGB attribute byte: bits 0–2 select palette 0–7; bit 3 selects tile-data bank; bits 5 and 6 flip horizontally and vertically; bit 7 sets BG/window priority. Keep unused bit 4 zero.

Return value

None (void).

Conditions and limits

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilebgcgb_unsafe
// Write a tile number and its CGB attribute. On DMG, only the tile-number write is
// performed. On CGB, enter with VRAM bank 0 selected; attributes use bank 1 and the call
// finishes with `VBK=0`. LCDC bit 3 selects the background map: zero uses `0x9800`, one
// uses `0x9C00`. The destination is that base plus `32*y + x`.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settilebgcgb_unsafe(2, 3, 'A', KQ_CGB_ATTR(2, 0, 0, 0, 0));
    if (tile_example_read(0x9C62, 0) != 'A') { failures++; }
    if (tile_example_read(0x9862, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C62, 1) != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB the A is blue: attribute value 2 selects the blue palette prepared by this example. On DMG the same character is black because CGB attributes are not applied.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilebgcgb_unsafe.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilebgcgb_unsafe.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Write tile and CGB attributes at the LCDC background map; DMG receives only the tile write. No VRAM access waits are inserted.

Write a tile number and its CGB attribute. On DMG, only the tile-number write is performed. On CGB, enter with VRAM bank 0 selected; attributes use bank 1 and the call finishes with VBK=0.

The destination is always 0x9800 + 32*y + x, regardless of which maps LCDC selects for the background and window.

Waits for writable VRAM when necessary. The LCD-on path uses interrupt masking and can enable interrupts afterward; it is not a promise to preserve the caller's interrupt state or to finish within one VBlank.

Syntax

void __settilecgb(u8 x, u8 y, u8 tile, u8 attr);

Parameters

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

tile

Tile number, 0–255. LCDC bit 4 determines how the number addresses tile-image data. It is not a VRAM byte address.

attr

CGB attribute byte: bits 0–2 select palette 0–7; bit 3 selects tile-data bank; bits 5 and 6 flip horizontally and vertically; bit 7 sets BG/window priority. Keep unused bit 4 zero.

Return value

None (void).

Conditions and limits

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilecgb
// Write a tile number and its CGB attribute. On DMG, only the tile-number write is
// performed. On CGB, enter with VRAM bank 0 selected; attributes use bank 1 and the call
// finishes with `VBK=0`. The destination is always `0x9800 + 32*y + x`, regardless of
// which maps LCDC selects for the background and window.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settilecgb(2, 3, 'A', KQ_CGB_ATTR(2, 0, 0, 0, 0));
    if (tile_example_read(0x9862, 0) != 'A') { failures++; }
    if (tile_example_read(0x9C62, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C62, 1) != 0) { failures++; }
    tile_example_finish(failures, 0);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB the A is blue: attribute value 2 selects the blue palette prepared by this example. On DMG the same character is black because CGB attributes are not applied.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilecgb.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilecgb.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Write tile and CGB attributes at map 9800; DMG receives only the tile write. Use the access-checked write path.

Copy count tile numbers from tile_src, then count attributes from attr_src, to the same map addresses starting at dest. These are separate byte arrays, not interleaved pairs.

Waits for writable VRAM when necessary. The LCD-on path uses interrupt masking and can enable interrupts afterward; it is not a promise to preserve the caller's interrupt state or to finish within one VBlank.

Syntax

void __settilecgb_bulk(u16 dest, const u8* tile_src, const u8* attr_src, u8 count);

Parameters

dest

First VRAM byte address. For a map, use an address in 0x9800–0x9FFF and keep the full transfer within the intended map.

tile_src, attr_src

Packed source bytes in RAM or a visible ROM bank. A tile stream contains tile numbers; an attribute stream contains CGB attribute bytes. The routine copies now and does not retain the pointer.

count

Number of bytes, 0–255. Zero copies nothing. Supply at least this many readable source bytes.

Return value

None (void).

Conditions and limits

Write a tile number and its CGB attribute. On DMG, only the tile-number write is performed. On CGB, enter with VRAM bank 0 selected; attributes use bank 1 and the call finishes with VBK=0.

Keep each source buffer readable and its ROM bank visible throughout the copy. Return type: void.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilecgb_bulk
// Copy `count` tile numbers from `tile_src`, then `count` attributes from `attr_src`, to
// the same map addresses starting at `dest`. These are separate byte arrays, not
// interleaved pairs. Waits for writable VRAM when necessary. The LCD-on path uses
// interrupt masking and can enable interrupts afterward; it is not a promise to preserve
// the caller's interrupt state or to finish within one VBlank.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"
const u8 example_tiles[] = {'A','B','C'};
const u8 example_attrs[] = {1,2,3};

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settilecgb_bulk(0x9862, example_tiles, example_attrs, 3);
    if (tile_example_read(0x9862, 0) != 'A') { failures++; }
    if (tile_example_read(0x9863, 0) != 'B') { failures++; }
    if (tile_example_read(0x9864, 0) != 'C') { failures++; }
    if (tile_example_read(0x9865, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 1) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9864, 1) != 3) { failures++; }
    tile_example_finish(failures, 0);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB, A, B and C are red, blue and green respectively: attribute bytes 1,2,3 select three different prepared palettes. On DMG all three are black.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

ABC

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilecgb_bulk.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilecgb_bulk.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Copy tile and attribute streams to dest; DMG receives only tiles. Keep both sources readable. Transfers use access checks.

Copy count tile numbers from tile_src, then count attributes from attr_src, to the same map addresses starting at dest. These are separate byte arrays, not interleaved pairs.

Does not wait for VRAM access. Call only while the LCD is off or within a caller-managed writable interval with enough time for the whole transfer.

Syntax

void __settilecgb_bulk_fast(u16 dest, const u8* tile_src, const u8* attr_src, u8 count);

Parameters

dest

First VRAM byte address. For a map, use an address in 0x9800–0x9FFF and keep the full transfer within the intended map.

tile_src, attr_src

Packed source bytes in RAM or a visible ROM bank. A tile stream contains tile numbers; an attribute stream contains CGB attribute bytes. The routine copies now and does not retain the pointer.

count

Number of bytes, 0–255. Zero copies nothing. Supply at least this many readable source bytes.

Return value

None (void).

Conditions and limits

Write a tile number and its CGB attribute. On DMG, only the tile-number write is performed. On CGB, enter with VRAM bank 0 selected; attributes use bank 1 and the call finishes with VBK=0.

Keep each source buffer readable and its ROM bank visible throughout the copy. Return type: void.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilecgb_bulk_fast
// Copy `count` tile numbers from `tile_src`, then `count` attributes from `attr_src`, to
// the same map addresses starting at `dest`. These are separate byte arrays, not
// interleaved pairs. Does not wait for VRAM access. Call only while the LCD is off or
// within a caller-managed writable interval with enough time for the whole transfer.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"
const u8 example_tiles[] = {'A','B','C'};
const u8 example_attrs[] = {1,2,3};

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settilecgb_bulk_fast(0x9862, example_tiles, example_attrs, 3);
    if (tile_example_read(0x9862, 0) != 'A') { failures++; }
    if (tile_example_read(0x9863, 0) != 'B') { failures++; }
    if (tile_example_read(0x9864, 0) != 'C') { failures++; }
    if (tile_example_read(0x9865, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 1) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9864, 1) != 3) { failures++; }
    tile_example_finish(failures, 0);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB, A, B and C are red, blue and green respectively: attribute bytes 1,2,3 select three different prepared palettes. On DMG all three are black.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

ABC

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilecgb_bulk_fast.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilecgb_bulk_fast.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Copy tile and attribute streams to dest; DMG receives only tiles. Keep both sources readable. The caller supplies writable VRAM timing.

Write a tile number and its CGB attribute. On DMG, only the tile-number write is performed. On CGB, enter with VRAM bank 0 selected; attributes use bank 1 and the call finishes with VBK=0.

The destination is always 0x9800 + 32*y + x, regardless of which maps LCDC selects for the background and window.

Does not wait for VRAM access. Call only while the LCD is off or within a caller-managed writable interval with enough time for the whole transfer.

Syntax

void __settilecgb_unsafe(u8 x, u8 y, u8 tile, u8 attr);

Parameters

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

tile

Tile number, 0–255. LCDC bit 4 determines how the number addresses tile-image data. It is not a VRAM byte address.

attr

CGB attribute byte: bits 0–2 select palette 0–7; bit 3 selects tile-data bank; bits 5 and 6 flip horizontally and vertically; bit 7 sets BG/window priority. Keep unused bit 4 zero.

Return value

None (void).

Conditions and limits

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilecgb_unsafe
// Write a tile number and its CGB attribute. On DMG, only the tile-number write is
// performed. On CGB, enter with VRAM bank 0 selected; attributes use bank 1 and the call
// finishes with `VBK=0`. The destination is always `0x9800 + 32*y + x`, regardless of
// which maps LCDC selects for the background and window.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settilecgb_unsafe(2, 3, 'A', KQ_CGB_ATTR(2, 0, 0, 0, 0));
    if (tile_example_read(0x9862, 0) != 'A') { failures++; }
    if (tile_example_read(0x9C62, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C62, 1) != 0) { failures++; }
    tile_example_finish(failures, 0);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB the A is blue: attribute value 2 selects the blue palette prepared by this example. On DMG the same character is black because CGB attributes are not applied.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilecgb_unsafe.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilecgb_unsafe.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Write tile and CGB attributes at map 9800; DMG receives only the tile write. No VRAM access waits are inserted.

Write one tile-number byte to the tile map; this selects an existing tile image, not new pixel data.

LCDC bit 6 selects the window map: zero uses 0x9800, one uses 0x9C00. These are map coordinates, not the window's screen position.

Waits for writable VRAM when necessary. The LCD-on path uses interrupt masking and can enable interrupts afterward; it is not a promise to preserve the caller's interrupt state or to finish within one VBlank.

Syntax

void __settilewin(u8 x, u8 y, u8 tile);

Parameters

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

tile

Tile number, 0–255. LCDC bit 4 determines how the number addresses tile-image data. It is not a VRAM byte address.

Return value

None (void).

Conditions and limits

Tile bytes go to the currently selected VRAM bank. On CGB, select bank 0 for tile numbers; this call does not switch banks for you.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilewin
// Write one tile-number byte to the tile map; this selects an existing tile image, not
// new pixel data. LCDC bit 6 selects the window map: zero uses `0x9800`, one uses
// `0x9C00`. These are map coordinates, not the window's screen position.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_color_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_color_example_begin();
    __settilewin(2, 3, 'A');
    if (tile_example_read(0x9C62, 0) != 'A') { failures++; }
    if (tile_example_read(0x9862, 0) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB, the sample characters and status text are blue on white. The setup gives palette 0 a blue ink color; it does not change the tile-map attributes. On DMG, the same characters are black on white.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilewin.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilewin.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Select the window map from LCDC bit 6, then write a tile with access checks.

Write one tile-number byte to the tile map; this selects an existing tile image, not new pixel data.

LCDC bit 6 selects the window map: zero uses 0x9800, one uses 0x9C00. These are map coordinates, not the window's screen position.

Does not wait for VRAM access. Call only while the LCD is off or within a caller-managed writable interval with enough time for the whole transfer.

Syntax

void __settilewin_unsafe(u8 x, u8 y, u8 tile);

Parameters

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

tile

Tile number, 0–255. LCDC bit 4 determines how the number addresses tile-image data. It is not a VRAM byte address.

Return value

None (void).

Conditions and limits

Tile bytes go to the currently selected VRAM bank. On CGB, select bank 0 for tile numbers; this call does not switch banks for you.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilewin_unsafe
// Write one tile-number byte to the tile map; this selects an existing tile image, not
// new pixel data. LCDC bit 6 selects the window map: zero uses `0x9800`, one uses
// `0x9C00`. These are map coordinates, not the window's screen position.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_color_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_color_example_begin();
    __settilewin_unsafe(2, 3, 'A');
    if (tile_example_read(0x9C62, 0) != 'A') { failures++; }
    if (tile_example_read(0x9862, 0) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB, the sample characters and status text are blue on white. The setup gives palette 0 a blue ink color; it does not change the tile-map attributes. On DMG, the same characters are black on white.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilewin_unsafe.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilewin_unsafe.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Select the LCDC window map and write without access waits.

Write only the CGB attribute byte; leave the tile number unchanged. Attribute bits select palette, tile-data bank, flips and priority.

LCDC bit 6 selects the window map: zero uses 0x9800, one uses 0x9C00. These are map coordinates, not the window's screen position.

Waits for writable VRAM when necessary. The LCD-on path uses interrupt masking and can enable interrupts afterward; it is not a promise to preserve the caller's interrupt state or to finish within one VBlank.

Syntax

void __settilewinattr(u8 x, u8 y, u8 attr);

Parameters

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

attr

CGB attribute byte: bits 0–2 select palette 0–7; bit 3 selects tile-data bank; bits 5 and 6 flip horizontally and vertically; bit 7 sets BG/window priority. Keep unused bit 4 zero.

Return value

None (void).

Conditions and limits

On CGB, temporarily selects VRAM bank 1 and leaves VBK=0 afterward. On DMG, no attribute write occurs.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilewinattr
// Write only the CGB attribute byte; leave the tile number unchanged. Attribute bits
// select palette, tile-data bank, flips and priority. LCDC bit 6 selects the window map:
// zero uses `0x9800`, one uses `0x9C00`. These are map coordinates, not the window's
// screen position.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settileat(0x9C00, 2, 3, 'A');
    __settilewinattr(2, 3, KQ_CGB_ATTR(2, 0, 0, 0, 0));
    if (tile_example_read(0x9C62, 0) != 'A') { failures++; }
    if (tile_example_read(0x9862, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C62, 1) != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB the A is blue: attribute value 2 selects the blue palette prepared by this example. On DMG the same character is black because CGB attributes are not applied.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilewinattr.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilewinattr.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Write attributes in bank one at the LCDC window map on CGB, then leave VBK zero; skip on DMG. Use the access-checked write path.

Write only the CGB attribute byte; leave the tile number unchanged. Attribute bits select palette, tile-data bank, flips and priority.

LCDC bit 6 selects the window map: zero uses 0x9800, one uses 0x9C00. These are map coordinates, not the window's screen position.

Does not wait for VRAM access. Call only while the LCD is off or within a caller-managed writable interval with enough time for the whole transfer.

Syntax

void __settilewinattr_unsafe(u8 x, u8 y, u8 attr);

Parameters

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

attr

CGB attribute byte: bits 0–2 select palette 0–7; bit 3 selects tile-data bank; bits 5 and 6 flip horizontally and vertically; bit 7 sets BG/window priority. Keep unused bit 4 zero.

Return value

None (void).

Conditions and limits

On CGB, temporarily selects VRAM bank 1 and leaves VBK=0 afterward. On DMG, no attribute write occurs.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilewinattr_unsafe
// Write only the CGB attribute byte; leave the tile number unchanged. Attribute bits
// select palette, tile-data bank, flips and priority. LCDC bit 6 selects the window map:
// zero uses `0x9800`, one uses `0x9C00`. These are map coordinates, not the window's
// screen position.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settileat(0x9C00, 2, 3, 'A');
    __settilewinattr_unsafe(2, 3, KQ_CGB_ATTR(2, 0, 0, 0, 0));
    if (tile_example_read(0x9C62, 0) != 'A') { failures++; }
    if (tile_example_read(0x9862, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C62, 1) != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB the A is blue: attribute value 2 selects the blue palette prepared by this example. On DMG the same character is black because CGB attributes are not applied.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilewinattr_unsafe.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilewinattr_unsafe.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Write attributes in bank one at the LCDC window map on CGB, then leave VBK zero; skip on DMG. No VRAM access waits are inserted.

Write a tile number and its CGB attribute. On DMG, only the tile-number write is performed. On CGB, enter with VRAM bank 0 selected; attributes use bank 1 and the call finishes with VBK=0.

LCDC bit 6 selects the window map: zero uses 0x9800, one uses 0x9C00. These are map coordinates, not the window's screen position.

Waits for writable VRAM when necessary. The LCD-on path uses interrupt masking and can enable interrupts afterward; it is not a promise to preserve the caller's interrupt state or to finish within one VBlank.

Syntax

void __settilewincgb(u8 x, u8 y, u8 tile, u8 attr);

Parameters

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

tile

Tile number, 0–255. LCDC bit 4 determines how the number addresses tile-image data. It is not a VRAM byte address.

attr

CGB attribute byte: bits 0–2 select palette 0–7; bit 3 selects tile-data bank; bits 5 and 6 flip horizontally and vertically; bit 7 sets BG/window priority. Keep unused bit 4 zero.

Return value

None (void).

Conditions and limits

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilewincgb
// Write a tile number and its CGB attribute. On DMG, only the tile-number write is
// performed. On CGB, enter with VRAM bank 0 selected; attributes use bank 1 and the call
// finishes with `VBK=0`. LCDC bit 6 selects the window map: zero uses `0x9800`, one uses
// `0x9C00`. These are map coordinates, not the window's screen position.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settilewincgb(2, 3, 'A', KQ_CGB_ATTR(2, 0, 0, 0, 0));
    if (tile_example_read(0x9C62, 0) != 'A') { failures++; }
    if (tile_example_read(0x9862, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C62, 1) != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB the A is blue: attribute value 2 selects the blue palette prepared by this example. On DMG the same character is black because CGB attributes are not applied.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilewincgb.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilewincgb.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Write tile and CGB attributes at the LCDC window map; DMG receives only the tile write. Use the access-checked write path.

Write a tile number and its CGB attribute. On DMG, only the tile-number write is performed. On CGB, enter with VRAM bank 0 selected; attributes use bank 1 and the call finishes with VBK=0.

LCDC bit 6 selects the window map: zero uses 0x9800, one uses 0x9C00. These are map coordinates, not the window's screen position.

Does not wait for VRAM access. Call only while the LCD is off or within a caller-managed writable interval with enough time for the whole transfer.

Syntax

void __settilewincgb_unsafe(u8 x, u8 y, u8 tile, u8 attr);

Parameters

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

tile

Tile number, 0–255. LCDC bit 4 determines how the number addresses tile-image data. It is not a VRAM byte address.

attr

CGB attribute byte: bits 0–2 select palette 0–7; bit 3 selects tile-data bank; bits 5 and 6 flip horizontally and vertically; bit 7 sets BG/window priority. Keep unused bit 4 zero.

Return value

None (void).

Conditions and limits

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilewincgb_unsafe
// Write a tile number and its CGB attribute. On DMG, only the tile-number write is
// performed. On CGB, enter with VRAM bank 0 selected; attributes use bank 1 and the call
// finishes with `VBK=0`. LCDC bit 6 selects the window map: zero uses `0x9800`, one uses
// `0x9C00`. These are map coordinates, not the window's screen position.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __settilewincgb_unsafe(2, 3, 'A', KQ_CGB_ATTR(2, 0, 0, 0, 0));
    if (tile_example_read(0x9C62, 0) != 'A') { failures++; }
    if (tile_example_read(0x9862, 0) != 0) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C62, 1) != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9862, 1) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB the A is blue: attribute value 2 selects the blue palette prepared by this example. On DMG the same character is black because CGB attributes are not applied.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilewincgb_unsafe.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilewincgb_unsafe.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

Write tile and CGB attributes at the LCDC window map; DMG receives only the tile write. No VRAM access waits are inserted.

Read all buttons and compare them with the supplied previous held mask. Pack the current mask into the low byte and newly pressed bits, current & ~previous, into the high byte. No previous state is stored internally and no release or repeat mask is returned.

Syntax

u16 __readpadex(u8 prev_keys);

Parameters

prev_keys

Previous full held mask from __readpad() or the low byte of the preceding __readpadex() result. Pass 0 on the first sample, then save the new low byte for the next call.

Return value

A u16: (u8)result is the current mask; (u8)(result >> 8) is the new-press mask. Store the result in a 16-bit variable or the press bits will be lost.

Conditions and limits

Shared masks: BTN_RIGHT=0x01, BTN_LEFT=0x02, BTN_UP=0x04, BTN_DOWN=0x08, BTN_A=0x10, BTN_B=0x20, BTN_SELECT=0x40, BTN_START=0x80. A set bit means held. This layout applies to input_* on both GB and FC; raw FC pad functions use a different order.

Usage example

packed_first=__readpadex(0); // First sample: current 0x11, new presses 0x11.
current_keys=(u8)packed_first;
press_keys=(u8)(packed_first>>8);
packed_held=__readpadex(current_keys); // Held without a change: new presses are 0.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Use this program to compare the three button-mask layouts and the packed press result. Hold A and Right together. ALL KEYS is 17; DIRECTIONS and BUTTONS LOW are each 1. With a previous mask of 0, EX CURRENT and EX NEW PRESS are both 17. Passing the current mask to the next read makes HELD PRESS 0. FAILED CHECKS must be 0. The values remain on screen after the snapshot, so releasing the buttons does not erase them.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\input_raw.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\input_raw.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm --no-cache

Obtain the logical ROM-bank number assigned to a named data object or function. This resolves placement information; it does not inspect the currently mapped bank or dereference a pointer.

Syntax

u8 bank = __bankof(symbol);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

symbol

The name of a ROM data object or function whose placement is known to the compiler or linker. A pointer variable does not mean the object it points to; runtime expressions are not accepted as symbol names.

Return value

A u8 bank number. Zero can identify common ROM; it is not necessarily a valid switch-bank selector on every target.

Usage example

bank_expect(__bankof(payload)==3,3);
bank_expect(__bankof(callback)==3,4);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The sample checks that both payload and callback are placed in bank 3. This proves placement metadata; separate reads and callback checks prove the runtime bank behavior.

The complete program teaches how a bank number and near address identify data, how callbacks cross banks, and how to distinguish the library's record from the actual mapping. All displayed numbers are hexadecimal. BANK IN and BANK OUT must show 02, BYTE HEX D3, WORD HEX 5C7A, and both FAILED CHECKS and FIRST FAILURE 00. CGB and FC display blue text; DMG displays black text.

CALL COUNT is 03: far_call, __farcall and __farcall_ptr each invoke the callback once.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\banked_data_calls.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

if (funcName == "__bankof")
            {
                if (args.Length != 1) Program.Error("__bankof(symbol) expects 1 argument");
                if (!args[0].Match(Tag.Name, out string symName)) Program.Error("__bankof(symbol) requires a symbol name argument");
                if (TryGetKnownRomBankForSymbol(symName, out int knownBank))
                {
                    EmitAsm("LD_A_IMM", new AsmOperand(knownBank & 0xFF, AddressMode.Immediate));
                    return;
                }
                EmitAsm("LD_A_IMM", new AsmOperand(symName, ImmediateModifier.Bank));
                return;
            }

Write the low bank byte to cartridge address $2000 and update the compiler's bank state. The selection remains in effect after this call; bank_get_current is not updated.

Syntax

void __bankswitch(u8 bank);

Parameters

bank

An unsigned 8-bit ROM-bank number. For a call, it must agree with the function's placement; for a read, it selects the source mapping. Use the target cartridge's valid range.

Return value

None (void).

Conditions and limits

A permanent bank change must not unmap the executing code or its return address. Put this call, bank_switch itself when used, and the code that continues afterwards in common/fixed bank 0, as the sample does.

The library record starts at zero and does not discover the cartridge's startup mapping. Initialize it with bank_switch. Direct intrinsics and raw mapper writes do not update this separate record; bank_get_current therefore cannot verify the actual hardware mapping.

These GB bank interfaces carry eight bank bits and do not set the ninth MBC5 bank bit. Cartridge rules still apply, including mapper-specific treatment of bank zero. The example explicitly uses MBC5 banks 1–3; do not mix this state with untracked raw mapper writes.

Usage example

__bankswitch(1);
bank_expect(home1[0]==0xA1,19);
bank_expect(bank_get_current()==2,20); // Intrinsics bypass the library record.
__bankswitch(2);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The initial bank_switch(2) records and selects bank 2. Later, direct switching selects bank 1 and reads A1 from home1 while bank_get_current still reports 2; switching back makes home2 read B2 again.

The complete program teaches how a bank number and near address identify data, how callbacks cross banks, and how to distinguish the library's record from the actual mapping. All displayed numbers are hexadecimal. BANK IN and BANK OUT must show 02, BYTE HEX D3, WORD HEX 5C7A, and both FAILED CHECKS and FIRST FAILURE 00. CGB and FC display blue text; DMG displays black text.

CALL COUNT is 03: far_call, __farcall and __farcall_ptr each invoke the callback once.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\banked_data_calls.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

if (funcName == "__bankswitch")
            {
                if (args.Length != 1) Program.Error("__bankswitch(bank) expects 1 argument");
                CompileIntoA(args[0]);
                if (CurrentFunctionBank == 0)
                {
                    EmitAsm("LD_MEM_A", new AsmOperand(0x2000, AddressMode.Absolute));
                    EmitStoreA(RomBankVar);
                }
                else
                {
                    UseBankSwitchBank0Helper = true;
                    EmitAsm("CALL", new AsmOperand("__kq_bankswitch_bank0", AddressMode.Absolute));
                }
                return;
            }

Write one byte to the background/window palette data register BCPD/BGPD at $FF69 on CGB. __cgb_safe_set_bcpd is another name for the same register. The associated index register selects the byte position; a full RGB15 color requires a low byte and a high byte.

Syntax

__cgb_safe_set_bgpd(/* 書式は実装と呼び出し例を参照 */);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

value

One byte, 0–255. Write the low byte followed by the high byte of RGB15; enable index auto-increment first, or explicitly select each position. A data write does not enable auto-increment itself.

Return value

None (void).

Conditions and limits

Palette and guarded register writes do nothing in DMG mode. Here, safe means a CGB-mode guard, not a PPU access wait or a critical section. Use LCD-off setup or a sufficiently short update in an accessible PPU phase. These functions do not wait for VBlank or protect a multi-byte update from interrupts.

Usage example

__cgb_safe_set_bgpd(31); __cgb_safe_set_bgpd(0); // Alias of BCPD: red at slot 31.
expect_color(0,31,31);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This program teaches how palette contents affect the same tile pattern differently in BG and OBJ. Each triangle is 8 × 8 pixels; its top row has one pixel on the left, expanding to a full bottom row. At x = 16, 32, 48, 64, 80, 96, 112, the BG row at y = 24 is red, blue, green, red, blue, green, red. The OBJ row at y = 64 is blue, green, red, blue, green, red, blue. The columns use single-color, component, indexed-range, full-palette, absolute-range, canonical-register and alias-register writes, respectively.

At y = 88, the seven 8 × 8 cells show: red triangle (x = 16), blue one-pixel square outline from bank 1 (32), horizontally reflected green triangle (48), vertically reflected red triangle (64), blue triangle reflected both ways (80), green triangle over a red sprite with red visible through color-zero pixels (96), and a full red sprite in front of the BG triangle as a priority control (112). Coordinates are screen pixels measured from the upper-left corner. Blank space and black text remain on white.

FAILED CHECKS 000 confirms RGB masking, truth-valued flags (including input 2), palette index wrapping, writes crossing a palette boundary, clamping at slot 31, null/zero-length no-ops and palette readback while LCD is off. Four target/hardware combinations are tested: dual-mode ROM on DMG and CGB, DMG-only on DMG, and CGB-only on CGB. On DMG, CGB MODE is 0, all triangles are black, the bank/flip attributes have no display effect, and the last two bottom cells are black squares. CGB MODE is 1 in CGB tests. Real hardware and LCD-on palette contention are not covered.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Write the background/window palette byte-index register BCPS/BGPI at $FF68 on CGB. __cgb_safe_set_bcps writes the same register. This selects where a subsequent data-register access goes; it does not itself write a color.

Syntax

__cgb_safe_set_bgpi(/* 書式は実装と呼び出し例を参照 */);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

value

Byte index in bits 0–5 (0–63), with bit 7 set for auto-increment after data writes; bit 6 is unused. Color slot n starts at byte 2n. Auto-increment wraps after byte 63, so raw register writes require your own range control.

Return value

None (void).

Conditions and limits

Palette and guarded register writes do nothing in DMG mode. Here, safe means a CGB-mode guard, not a PPU access wait or a critical section. Use LCD-off setup or a sufficiently short update in an accessible PPU phase. These functions do not wait for VBlank or protect a multi-byte update from interrupts.

Usage example

__cgb_safe_set_bgpi(0xBE); // Alias of BCPS: BG byte 62, auto-increment enabled.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This program teaches how palette contents affect the same tile pattern differently in BG and OBJ. Each triangle is 8 × 8 pixels; its top row has one pixel on the left, expanding to a full bottom row. At x = 16, 32, 48, 64, 80, 96, 112, the BG row at y = 24 is red, blue, green, red, blue, green, red. The OBJ row at y = 64 is blue, green, red, blue, green, red, blue. The columns use single-color, component, indexed-range, full-palette, absolute-range, canonical-register and alias-register writes, respectively.

At y = 88, the seven 8 × 8 cells show: red triangle (x = 16), blue one-pixel square outline from bank 1 (32), horizontally reflected green triangle (48), vertically reflected red triangle (64), blue triangle reflected both ways (80), green triangle over a red sprite with red visible through color-zero pixels (96), and a full red sprite in front of the BG triangle as a priority control (112). Coordinates are screen pixels measured from the upper-left corner. Blank space and black text remain on white.

FAILED CHECKS 000 confirms RGB masking, truth-valued flags (including input 2), palette index wrapping, writes crossing a palette boundary, clamping at slot 31, null/zero-length no-ops and palette readback while LCD is off. Four target/hardware combinations are tested: dual-mode ROM on DMG and CGB, DMG-only on DMG, and CGB-only on CGB. On DMG, CGB MODE is 0, all triangles are black, the bank/flip attributes have no display effect, and the last two bottom cells are black squares. CGB MODE is 1 in CGB tests. Real hardware and LCD-on palette contention are not covered.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Write HDMA1 ($FF51), the high byte of the CGB DMA source address. This configures the source; it neither copies data nor starts a transfer. Set HDMA2 for the low byte.

Syntax

void __cgb_safe_set_hdma1(u8 value);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

value

Register value as u8 (0–255). The bit meanings for this particular register are given above; the function accepts a byte, not a pointer or a byte count.

Return value

None (void).

Conditions and limits

Writes are guarded by the compiler's CGB-mode check and do nothing in DMG mode. Safe denotes this mode guard only. The call does not save or restore the previous register value.

One block is 16 bytes. New transfers support 1–128 blocks (16–2048 bytes), so control value 0 means 16 bytes, not an empty transfer. GDMA pauses the CPU until complete. HBlank DMA transfers one block per visible-line HBlank and runs across frames; the caller must poll or otherwise track completion before reusing its data.

Use GDMA with the LCD off or within a sufficiently long writable period. Start HBlank DMA with the LCD running, outside STAT mode 0; this sample starts it in VBlank. Do not change source banks, destination VBK or the source data while it is active. HALT pauses HBlank DMA too. No wait, interrupt protection or source/destination range check is added by these setters.

Read $FF55 separately: bit 7 clear means active; $FF means completed. After cancellation, bit 7 is set and bits 0–6 retain remaining blocks minus one. Cancellation does not undo copied bytes. Only issue a cancel command while a transfer is active; otherwise bit 7 clear starts GDMA. Keep the entire transfer inside valid source memory and the destination VRAM bank; do not rely on address overflow.

These HDMA register setters control CGB hardware DMA. __vram_copy_dma is a separate compiler alias for a CPU copy loop; its name does not make it use this DMA controller.

Usage example

__cgb_safe_set_hdma1(0xC6); // Source high byte: fixed-WRAM buffer at $C600.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The complete program compares three transfer paths using a 16-byte-aligned buffer at $C600. GDMA copies 32 bytes to $8010: at screen (16,24) a red 8 × 8 triangle grows from one leftmost pixel to a full bottom row, followed at (24,24) by a red one-pixel square outline. HBlank DMA copies 32 bytes to $8030: at (16,48) a blue 4 × 8 left half-tile is followed at (24,48) by a blue 8 × 8 square. These are actual transferred tile patterns, not numerical placeholders.

The CANCELED row contains a green 4 × 8 half-tile at (16,72) and a green 8 × 8 square at (24,72), initially written by the CPU. A two-block HBlank transfer targeting these tiles is armed and canceled in the same VBlank, before its first block; $FF55 must read $81, and both patterns must remain unchanged after a frame. On DMG, the first two rows stay blank and only these two sentinels appear in black. Text remains black on white. FAILED CHECKS 000 also checks copied bytes and completion status. The test covers dual-mode DMG/CGB and CGB-only execution in KOKURA; partial cancellation, double speed and real hardware are not tested.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_dma_shapes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_dma_shapes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Write HDMA2 ($FF52), the low byte of the DMA source address. Hardware ignores bits 0–3, aligning the source downward to 16 bytes. For example, HDMA1=$C6, HDMA2=$0F selects $C600. It does not start DMA.

Syntax

void __cgb_safe_set_hdma2(u8 value);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

value

Register value as u8 (0–255). The bit meanings for this particular register are given above; the function accepts a byte, not a pointer or a byte count.

Return value

None (void).

Conditions and limits

Writes are guarded by the compiler's CGB-mode check and do nothing in DMG mode. Safe denotes this mode guard only. The call does not save or restore the previous register value.

One block is 16 bytes. New transfers support 1–128 blocks (16–2048 bytes), so control value 0 means 16 bytes, not an empty transfer. GDMA pauses the CPU until complete. HBlank DMA transfers one block per visible-line HBlank and runs across frames; the caller must poll or otherwise track completion before reusing its data.

Use GDMA with the LCD off or within a sufficiently long writable period. Start HBlank DMA with the LCD running, outside STAT mode 0; this sample starts it in VBlank. Do not change source banks, destination VBK or the source data while it is active. HALT pauses HBlank DMA too. No wait, interrupt protection or source/destination range check is added by these setters.

Read $FF55 separately: bit 7 clear means active; $FF means completed. After cancellation, bit 7 is set and bits 0–6 retain remaining blocks minus one. Cancellation does not undo copied bytes. Only issue a cancel command while a transfer is active; otherwise bit 7 clear starts GDMA. Keep the entire transfer inside valid source memory and the destination VRAM bank; do not rely on address overflow.

These HDMA register setters control CGB hardware DMA. __vram_copy_dma is a separate compiler alias for a CPU copy loop; its name does not make it use this DMA controller.

Usage example

__cgb_safe_set_hdma2(0x0F); // Low four bits are ignored by hardware: source remains $C600.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The complete program compares three transfer paths using a 16-byte-aligned buffer at $C600. GDMA copies 32 bytes to $8010: at screen (16,24) a red 8 × 8 triangle grows from one leftmost pixel to a full bottom row, followed at (24,24) by a red one-pixel square outline. HBlank DMA copies 32 bytes to $8030: at (16,48) a blue 4 × 8 left half-tile is followed at (24,48) by a blue 8 × 8 square. These are actual transferred tile patterns, not numerical placeholders.

The CANCELED row contains a green 4 × 8 half-tile at (16,72) and a green 8 × 8 square at (24,72), initially written by the CPU. A two-block HBlank transfer targeting these tiles is armed and canceled in the same VBlank, before its first block; $FF55 must read $81, and both patterns must remain unchanged after a frame. On DMG, the first two rows stay blank and only these two sentinels appear in black. Text remains black on white. FAILED CHECKS 000 also checks copied bytes and completion status. The test covers dual-mode DMG/CGB and CGB-only execution in KOKURA; partial cancellation, double speed and real hardware are not tested.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_dma_shapes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_dma_shapes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Write HDMA3 ($FF53), the high part of the DMA destination within VRAM. Only bits 0–4 are used; the destination is always in $8000–$9FFF. Pair it with HDMA4. This does not select the VRAM bank or start DMA.

Syntax

void __cgb_safe_set_hdma3(u8 value);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

value

Register value as u8 (0–255). The bit meanings for this particular register are given above; the function accepts a byte, not a pointer or a byte count.

Return value

None (void).

Conditions and limits

Writes are guarded by the compiler's CGB-mode check and do nothing in DMG mode. Safe denotes this mode guard only. The call does not save or restore the previous register value.

One block is 16 bytes. New transfers support 1–128 blocks (16–2048 bytes), so control value 0 means 16 bytes, not an empty transfer. GDMA pauses the CPU until complete. HBlank DMA transfers one block per visible-line HBlank and runs across frames; the caller must poll or otherwise track completion before reusing its data.

Use GDMA with the LCD off or within a sufficiently long writable period. Start HBlank DMA with the LCD running, outside STAT mode 0; this sample starts it in VBlank. Do not change source banks, destination VBK or the source data while it is active. HALT pauses HBlank DMA too. No wait, interrupt protection or source/destination range check is added by these setters.

Read $FF55 separately: bit 7 clear means active; $FF means completed. After cancellation, bit 7 is set and bits 0–6 retain remaining blocks minus one. Cancellation does not undo copied bytes. Only issue a cancel command while a transfer is active; otherwise bit 7 clear starts GDMA. Keep the entire transfer inside valid source memory and the destination VRAM bank; do not rely on address overflow.

These HDMA register setters control CGB hardware DMA. __vram_copy_dma is a separate compiler alias for a CPU copy loop; its name does not make it use this DMA controller.

Usage example

__cgb_safe_set_hdma3(0xE0); // Only low five bits select the high VRAM offset.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The complete program compares three transfer paths using a 16-byte-aligned buffer at $C600. GDMA copies 32 bytes to $8010: at screen (16,24) a red 8 × 8 triangle grows from one leftmost pixel to a full bottom row, followed at (24,24) by a red one-pixel square outline. HBlank DMA copies 32 bytes to $8030: at (16,48) a blue 4 × 8 left half-tile is followed at (24,48) by a blue 8 × 8 square. These are actual transferred tile patterns, not numerical placeholders.

The CANCELED row contains a green 4 × 8 half-tile at (16,72) and a green 8 × 8 square at (24,72), initially written by the CPU. A two-block HBlank transfer targeting these tiles is armed and canceled in the same VBlank, before its first block; $FF55 must read $81, and both patterns must remain unchanged after a frame. On DMG, the first two rows stay blank and only these two sentinels appear in black. Text remains black on white. FAILED CHECKS 000 also checks copied bytes and completion status. The test covers dual-mode DMG/CGB and CGB-only execution in KOKURA; partial cancellation, double speed and real hardware are not tested.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_dma_shapes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_dma_shapes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Write HDMA4 ($FF54), the low byte of the VRAM destination address. Bits 0–3 are ignored, so the destination is aligned downward to 16 bytes. HDMA3=$E0, HDMA4=$1F selects $8010. This sets an address, not a transfer length.

Syntax

void __cgb_safe_set_hdma4(u8 value);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

value

Register value as u8 (0–255). The bit meanings for this particular register are given above; the function accepts a byte, not a pointer or a byte count.

Return value

None (void).

Conditions and limits

Writes are guarded by the compiler's CGB-mode check and do nothing in DMG mode. Safe denotes this mode guard only. The call does not save or restore the previous register value.

One block is 16 bytes. New transfers support 1–128 blocks (16–2048 bytes), so control value 0 means 16 bytes, not an empty transfer. GDMA pauses the CPU until complete. HBlank DMA transfers one block per visible-line HBlank and runs across frames; the caller must poll or otherwise track completion before reusing its data.

Use GDMA with the LCD off or within a sufficiently long writable period. Start HBlank DMA with the LCD running, outside STAT mode 0; this sample starts it in VBlank. Do not change source banks, destination VBK or the source data while it is active. HALT pauses HBlank DMA too. No wait, interrupt protection or source/destination range check is added by these setters.

Read $FF55 separately: bit 7 clear means active; $FF means completed. After cancellation, bit 7 is set and bits 0–6 retain remaining blocks minus one. Cancellation does not undo copied bytes. Only issue a cancel command while a transfer is active; otherwise bit 7 clear starts GDMA. Keep the entire transfer inside valid source memory and the destination VRAM bank; do not rely on address overflow.

These HDMA register setters control CGB hardware DMA. __vram_copy_dma is a separate compiler alias for a CPU copy loop; its name does not make it use this DMA controller.

Usage example

__cgb_safe_set_hdma4(0x1F); // Destination aligns to $8010, not $801F.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The complete program compares three transfer paths using a 16-byte-aligned buffer at $C600. GDMA copies 32 bytes to $8010: at screen (16,24) a red 8 × 8 triangle grows from one leftmost pixel to a full bottom row, followed at (24,24) by a red one-pixel square outline. HBlank DMA copies 32 bytes to $8030: at (16,48) a blue 4 × 8 left half-tile is followed at (24,48) by a blue 8 × 8 square. These are actual transferred tile patterns, not numerical placeholders.

The CANCELED row contains a green 4 × 8 half-tile at (16,72) and a green 8 × 8 square at (24,72), initially written by the CPU. A two-block HBlank transfer targeting these tiles is armed and canceled in the same VBlank, before its first block; $FF55 must read $81, and both patterns must remain unchanged after a frame. On DMG, the first two rows stay blank and only these two sentinels appear in black. Text remains black on white. FAILED CHECKS 000 also checks copied bytes and completion status. The test covers dual-mode DMG/CGB and CGB-only execution in KOKURA; partial cancellation, double speed and real hardware are not tested.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_dma_shapes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_dma_shapes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Write HDMA5 ($FF55) to start DMA, or cancel an active HBlank transfer. For a new transfer, bits 0–6 encode block count minus one and bit 7 chooses GDMA (0) or HBlank DMA (1). During an active HBlank transfer, writing bit 7 clear cancels the remaining work; it does not start a new GDMA transfer.

Syntax

void __cgb_safe_set_hdma5(u8 value);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

value

Register value as u8 (0–255). The bit meanings for this particular register are given above; the function accepts a byte, not a pointer or a byte count.

Return value

None (void).

Conditions and limits

Writes are guarded by the compiler's CGB-mode check and do nothing in DMG mode. Safe denotes this mode guard only. The call does not save or restore the previous register value.

One block is 16 bytes. New transfers support 1–128 blocks (16–2048 bytes), so control value 0 means 16 bytes, not an empty transfer. GDMA pauses the CPU until complete. HBlank DMA transfers one block per visible-line HBlank and runs across frames; the caller must poll or otherwise track completion before reusing its data.

Use GDMA with the LCD off or within a sufficiently long writable period. Start HBlank DMA with the LCD running, outside STAT mode 0; this sample starts it in VBlank. Do not change source banks, destination VBK or the source data while it is active. HALT pauses HBlank DMA too. No wait, interrupt protection or source/destination range check is added by these setters.

Read $FF55 separately: bit 7 clear means active; $FF means completed. After cancellation, bit 7 is set and bits 0–6 retain remaining blocks minus one. Cancellation does not undo copied bytes. Only issue a cancel command while a transfer is active; otherwise bit 7 clear starts GDMA. Keep the entire transfer inside valid source memory and the destination VRAM bank; do not rely on address overflow.

These HDMA register setters control CGB hardware DMA. __vram_copy_dma is a separate compiler alias for a CPU copy loop; its name does not make it use this DMA controller.

Usage example

__cgb_safe_set_hdma5(1); // LCD is off: GDMA, (1+1)*16 = 32 bytes.
if (color_mode && D_CONTROL!=255) failures++;

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The complete program compares three transfer paths using a 16-byte-aligned buffer at $C600. GDMA copies 32 bytes to $8010: at screen (16,24) a red 8 × 8 triangle grows from one leftmost pixel to a full bottom row, followed at (24,24) by a red one-pixel square outline. HBlank DMA copies 32 bytes to $8030: at (16,48) a blue 4 × 8 left half-tile is followed at (24,48) by a blue 8 × 8 square. These are actual transferred tile patterns, not numerical placeholders.

The CANCELED row contains a green 4 × 8 half-tile at (16,72) and a green 8 × 8 square at (24,72), initially written by the CPU. A two-block HBlank transfer targeting these tiles is armed and canceled in the same VBlank, before its first block; $FF55 must read $81, and both patterns must remain unchanged after a frame. On DMG, the first two rows stay blank and only these two sentinels appear in black. Text remains black on white. FAILED CHECKS 000 also checks copied bytes and completion status. The test covers dual-mode DMG/CGB and CGB-only execution in KOKURA; partial cancellation, double speed and real hardware are not tested.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_dma_shapes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_dma_shapes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Write one byte to the sprite (OBJ) palette data register OCPD/OBPD at $FF6B on CGB. __cgb_safe_set_ocpd is another name for the same register. The associated index register selects the byte position; a full RGB15 color requires a low byte and a high byte.

Syntax

__cgb_safe_set_obpd(/* 書式は実装と呼び出し例を参照 */);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

value

One byte, 0–255. Write the low byte followed by the high byte of RGB15; enable index auto-increment first, or explicitly select each position. A data write does not enable auto-increment itself.

Return value

None (void).

Conditions and limits

Palette and guarded register writes do nothing in DMG mode. Here, safe means a CGB-mode guard, not a PPU access wait or a critical section. Use LCD-off setup or a sufficiently short update in an accessible PPU phase. These functions do not wait for VBlank or protect a multi-byte update from interrupts.

Usage example

__cgb_safe_set_obpd(0); __cgb_safe_set_obpd(0x7C); // Alias of OCPD: blue at slot 31.
expect_color(1,31,31744);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This program teaches how palette contents affect the same tile pattern differently in BG and OBJ. Each triangle is 8 × 8 pixels; its top row has one pixel on the left, expanding to a full bottom row. At x = 16, 32, 48, 64, 80, 96, 112, the BG row at y = 24 is red, blue, green, red, blue, green, red. The OBJ row at y = 64 is blue, green, red, blue, green, red, blue. The columns use single-color, component, indexed-range, full-palette, absolute-range, canonical-register and alias-register writes, respectively.

At y = 88, the seven 8 × 8 cells show: red triangle (x = 16), blue one-pixel square outline from bank 1 (32), horizontally reflected green triangle (48), vertically reflected red triangle (64), blue triangle reflected both ways (80), green triangle over a red sprite with red visible through color-zero pixels (96), and a full red sprite in front of the BG triangle as a priority control (112). Coordinates are screen pixels measured from the upper-left corner. Blank space and black text remain on white.

FAILED CHECKS 000 confirms RGB masking, truth-valued flags (including input 2), palette index wrapping, writes crossing a palette boundary, clamping at slot 31, null/zero-length no-ops and palette readback while LCD is off. Four target/hardware combinations are tested: dual-mode ROM on DMG and CGB, DMG-only on DMG, and CGB-only on CGB. On DMG, CGB MODE is 0, all triangles are black, the bank/flip attributes have no display effect, and the last two bottom cells are black squares. CGB MODE is 1 in CGB tests. Real hardware and LCD-on palette contention are not covered.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Write the sprite (OBJ) palette byte-index register OCPS/OBPI at $FF6A on CGB. __cgb_safe_set_ocps writes the same register. This selects where a subsequent data-register access goes; it does not itself write a color.

Syntax

__cgb_safe_set_obpi(/* 書式は実装と呼び出し例を参照 */);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

value

Byte index in bits 0–5 (0–63), with bit 7 set for auto-increment after data writes; bit 6 is unused. Color slot n starts at byte 2n. Auto-increment wraps after byte 63, so raw register writes require your own range control.

Return value

None (void).

Conditions and limits

Palette and guarded register writes do nothing in DMG mode. Here, safe means a CGB-mode guard, not a PPU access wait or a critical section. Use LCD-off setup or a sufficiently short update in an accessible PPU phase. These functions do not wait for VBlank or protect a multi-byte update from interrupts.

Usage example

__cgb_safe_set_obpi(0xBE); // Alias of OCPS: select the OBJ store's last word.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This program teaches how palette contents affect the same tile pattern differently in BG and OBJ. Each triangle is 8 × 8 pixels; its top row has one pixel on the left, expanding to a full bottom row. At x = 16, 32, 48, 64, 80, 96, 112, the BG row at y = 24 is red, blue, green, red, blue, green, red. The OBJ row at y = 64 is blue, green, red, blue, green, red, blue. The columns use single-color, component, indexed-range, full-palette, absolute-range, canonical-register and alias-register writes, respectively.

At y = 88, the seven 8 × 8 cells show: red triangle (x = 16), blue one-pixel square outline from bank 1 (32), horizontally reflected green triangle (48), vertically reflected red triangle (64), blue triangle reflected both ways (80), green triangle over a red sprite with red visible through color-zero pixels (96), and a full red sprite in front of the BG triangle as a priority control (112). Coordinates are screen pixels measured from the upper-left corner. Blank space and black text remain on white.

FAILED CHECKS 000 confirms RGB masking, truth-valued flags (including input 2), palette index wrapping, writes crossing a palette boundary, clamping at slot 31, null/zero-length no-ops and palette readback while LCD is off. Four target/hardware combinations are tested: dual-mode ROM on DMG and CGB, DMG-only on DMG, and CGB-only on CGB. On DMG, CGB MODE is 0, all triangles are black, the bank/flip attributes have no display effect, and the last two bottom cells are black squares. CGB MODE is 1 in CGB tests. Real hardware and LCD-on palette contention are not covered.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Write the raw WRAM selector SVBK ($FF70) on CGB. Hardware uses bits 0–2; raw values 0 and 1 both map bank 1 at $D000–$DFFF. For example, 8 also maps bank 1. Unlike __svbk_set, this guarded setter permits a dual-mode target and does not return the previous bank.

Syntax

void __cgb_safe_set_svbk(u8 value);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

value

Register value as u8 (0–255). The bit meanings for this particular register are given above; the function accepts a byte, not a pointer or a byte count.

Return value

None (void).

Conditions and limits

Writes are guarded by the compiler's CGB-mode check and do nothing in DMG mode. Safe denotes this mode guard only. The call does not save or restore the previous register value.

Switching banks changes every access in $D000–$DFFF; fixed WRAM at $C000–$CFFF stays mapped. Keep the stack and all state needed during the switch outside the switched window. The sample uses --stack-bank=fixed and explicitly located fixed-WRAM state. Coordinate interrupts and banked DMA with the switch; these APIs add no critical section.

Usage example

__cgb_safe_set_svbk(0); // Raw selector 0 maps effective bank 1; this API returns void.
if ((W_SELECTOR&7)!=0) failures++;

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The complete CGB-only program stores 1 at $D100 in WRAM bank 2 and 2 at the same address in bank 3, then reads both back and restores bank 1. The values choose an 8 × 8 red square at (16,24) and a blue one-pixel 8 × 8 square outline at (16,48). FAILED CHECKS 000 checks raw-selector normalization, bank separation and the previous-bank return for constant, variable, arithmetic and function-result arguments. Six separate invalid-build fixtures verify KQ2103 for DMG/dual targets and KQ2102 for constant banks 0 and 8. Runtime verification uses KOKURA; real hardware and interrupt-driven concurrent bank changes are not tested.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_wram_banks.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_wram_banks.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb_only --no-cache --no-disasm

Increment software nesting depth and execute DI.

Syntax

u8 __critical_enter();

Return value

Returns the previous depth as a u8 token: zero for the outer scope, one for its first nested scope.

Conditions and limits

Pass tokens to leave in reverse order and avoid depth wrapping at 256. Previous hardware IME is not saved; do not use this pair where a pre-existing DI state must be preserved.

Usage example

*((u8*)0xFFFF)=0;outer=__critical_enter();inner=__critical_enter();result[7]=outer;result[8]=inner;

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Learn map selection, scrolling, nesting and scanline waits. Bases are 38912/39936; nested tokens are 0/1; observed target LY values are 80/144. Also verify waits return with the LCD off.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch3_display.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch3_display.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --ramsize=none

if (funcName == "__critical_enter")
            {
                if (args.Length != 0) Error(expr, "__critical_enter() expects 0 arguments");

                EmitLoadA(CriticalDepthVar);
                EmitAsm("LD_B_A"); // token = old depth
                EmitAsm("INC_A");
                EmitStoreA(CriticalDepthVar);
                EmitAsm("DI");
                EmitAsm("LD_A_B");
                return;
            }

Decrease nesting depth and execute EI for outer token zero.

Syntax

void __critical_leave(u8 token);

Parameters

token

Token returned by the matching __critical_enter.

Return value

No return value.

Conditions and limits

Nonzero tokens do not execute EI. Passing an arbitrary zero can enable interrupts despite other active scopes; pair calls correctly.

Usage example

__critical_leave(inner);__critical_leave(outer);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Learn map selection, scrolling, nesting and scanline waits. Bases are 38912/39936; nested tokens are 0/1; observed target LY values are 80/144. Also verify waits return with the LCD off.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch3_display.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch3_display.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --ramsize=none

if (funcName == "__critical_leave")
            {
                if (args.Length != 1) Error(expr, "__critical_leave(token) expects 1 argument");

                CompileIntoA(args[0]);
                EmitAsm("LD_B_A"); // token

                AsmOperand clAfterDec = MakeUniqueLabel("critleave_afterdec");
                AsmOperand clDone = MakeUniqueLabel("critleave_done");

                EmitLoadA(CriticalDepthVar);
                EmitAsm("OR_A");
                EmitAsm("JR_Z", clAfterDec);
                EmitAsm("DEC_A");
                EmitStoreA(CriticalDepthVar);
                EmitLabel(clAfterDec);

                // Re-enable only for outermost token (token==0).
                EmitAsm("LD_A_B");
                EmitAsm("OR_A");
                EmitAsm("JR_NZ", clDone);
                EmitAsm("EI");
                EmitLabel(clDone);
                return;
            }

Compute a unsigned two-term dot product.

Syntax

u16 __dot2_q8_8(u16 a0, u16 a1, u8 b0, u8 b1);

Parameters

a0

Unsigned word, 0..65535.

a1

Unsigned word, 0..65535.

b0

Unsigned coefficient, 0..255.

b1

Unsigned coefficient, 0..255.

Return value

Each term is floor(a*b/256). Sum the terms; returns the low 16 bits.

Conditions and limits

GB products are divided by 256; signed results truncate toward zero. Q1.7 variants double that truncated result and can differ by one from exact division by 128. Terms are rounded separately; final addition wraps at 16 bits.

Usage example

// Compare literal coefficients with values read from RAM.
result[36]=__dot2_q8_8(513,769,64,127);
v0=513;v1=769;v2=64;v3=127;
result[37]=__dot2_q8_8(v0,v1,v2,v3);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Compare literal inputs with values stored in RAM. Representative results appear as unsigned 16-bit values; negatives use two’s-complement bit patterns. GB rescales fixed-point products, while FC returns integer products, so identical inputs need not give identical results.

The excerpt stores these 16-bit values: result[36]=509, result[37]=509. Each literal-input calculation matches its RAM-input counterpart. The screen shows representative values; the result array holds every result.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch3_math.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch3_math.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --ramsize=none

if (funcName == "__dot2_q8_8")
{
    if (args.Length != 4) Error(expr, "__dot2_q8_8 requires 4 arguments");
    LastCallReturnsHL = true;

    // Fast paths when coefficients are compile-time constants.
    // Special-case: 0 / power-of-two coefficients (u8) => shift instead of mul.
    if (TryGetU8Const(args[2], out int ax0) && (ax0 == 0) && TryGetU8Const(args[3], out int ay0) && (ay0 == 0))
    {
        CompileDiscard(args[0]);
        CompileDiscard(args[1]);
        EmitAsm("XOR_A");
        EmitAsm("LD_H_A");
        EmitAsm("LD_L_A");
        return;
    }
    if (TryGetU8Const(args[2], out int axOnly) && (axOnly == 0))
    {
        CompileDiscard(args[0]);
        // only y*ay
        if (!TryEmitDot2Pow2Term(args[1], args[3], signed: false, q1_7: false, out _))
        {
            CompileIntoHL(args[1]);
            EmitAsm("PUSH_HL");
            CompileIntoA(args[3]);
            EmitAsm("LD_C_A");
            EmitAsm("POP_HL");
            EmitMul16x8Shr8_HL("__dot2_y");
        }
        return;
    }
    if (TryGetU8Const(args[3], out int ayOnly) && (ayOnly == 0))
    {
        // only x*ax
        if (!TryEmitDot2Pow2Term(args[0], args[2], signed: false, q1_7: false, out _))
        {
            CompileIntoHL(args[0]);
            EmitAsm("PUSH_HL");
            CompileIntoA(args[2]);
            EmitAsm("LD_C_A");
            EmitAsm("POP_HL");
            EmitMul16x8Shr8_HL("__dot2_x");
        }
        // Preserve the scaled result while evaluating the zero-product input.
        EmitAsm("PUSH_HL");
        CompileDiscard(args[1]);
        EmitAsm("POP_HL");
        return;
    }

    // x*ax
    if (!TryEmitDot2Pow2Term(args[0], args[2], signed: false, q1_7: false, out _))
    {
        CompileIntoHL(args[0]);
        EmitAsm("PUSH_HL");
        CompileIntoA(args[2]);
        EmitAsm("LD_C_A");
        EmitAsm("POP_HL");
        EmitMul16x8Shr8_HL("__dot2_x");
    }
    EmitAsm("PUSH_HL");

    // y*ay
    if (!TryEmitDot2Pow2Term(args[1], args[3], signed: false, q1_7: false, out _))
    {
        CompileIntoHL(args[1]);
        EmitAsm("PUSH_HL");
        CompileIntoA(args[3]);
        EmitAsm("LD_C_A");
        EmitAsm("POP_HL");
        EmitMul16x8Shr8_HL("__dot2_y");
    }
    EmitAsm("POP_DE");
    EmitAsm("ADD_HL_DE");
    return;
}

Compute a unsigned three-term dot product.

Syntax

u16 __dot3_q8_8(u16 a0, u16 a1, u16 a2, u8 b0, u8 b1, u8 b2);

Parameters

a0

Unsigned word, 0..65535.

a1

Unsigned word, 0..65535.

a2

Unsigned word, 0..65535.

b0

Unsigned coefficient, 0..255.

b1

Unsigned coefficient, 0..255.

b2

Unsigned coefficient, 0..255.

Return value

Each term is floor(a*b/256). Sum the terms; returns the low 16 bits.

Conditions and limits

GB products are divided by 256; signed results truncate toward zero. Q1.7 variants double that truncated result and can differ by one from exact division by 128. Terms are rounded separately; final addition wraps at 16 bits.

Usage example

// Compare literal coefficients with values read from RAM.
result[6]=__dot3_q8_8(513,769,1025,64,127,3);
v0=513;v1=769;v2=1025;v3=64;v4=127;v5=3;
result[7]=__dot3_q8_8(v0,v1,v2,v3,v4,v5);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Compare literal inputs with values stored in RAM. Representative results appear as unsigned 16-bit values; negatives use two’s-complement bit patterns. GB rescales fixed-point products, while FC returns integer products, so identical inputs need not give identical results.

The excerpt stores these 16-bit values: result[6]=521, result[7]=521. Each literal-input calculation matches its RAM-input counterpart. The screen shows representative values; the result array holds every result.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch3_math.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch3_math.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --ramsize=none

if (funcName == "__dot3_q8_8")
            {
                if (args.Length != 6) Error(expr, "__dot3_q8_8 requires 6 arguments");
                LastCallReturnsHL = true;

                // x*ax
                EmitDotTermToHL(args[0], args[3], signed: false, q1_7: false, labelPrefix: "__dot3_x");
                EmitAsm("PUSH_HL");

                // y*ay
                EmitDotTermToHL(args[1], args[4], signed: false, q1_7: false, labelPrefix: "__dot3_y");
                EmitAsm("POP_DE");
                EmitAsm("ADD_HL_DE");
                EmitAsm("PUSH_HL");

                // z*az
                EmitDotTermToHL(args[2], args[5], signed: false, q1_7: false, labelPrefix: "__dot3_z");
                EmitAsm("POP_DE");
                EmitAsm("ADD_HL_DE");
                return;
            }

Call a named, zero-argument function using the supplied bank number. When a bank change is needed, a helper in fixed ROM restores the caller's bank after the function returns.

Syntax

__farcall(bank, function_name);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

bank

An unsigned 8-bit ROM-bank number. For a call, it must agree with the function's placement; for a read, it selects the source mapping. Use the target cartridge's valid range.

func

The declared name of a function with no parameters. A variable holding a function address is not accepted by this named-call intrinsic. The bank argument is not forwarded as a callback parameter.

Return value

The called function's result type determines the result. A void callback yields no value; u8 and u16 callbacks return their scalar value. The displayed sample uses void callbacks.

Conditions and limits

These calls do not forward user arguments or make the callback interrupt-reentrant. Keep the callback's own data, stack and interrupt use valid. The bank-restoring call paths are tested with nested calls and repeated calls; physical hardware and arbitrary interrupt interleavings are not covered by this example.

These GB bank interfaces carry eight bank bits and do not set the ninth MBC5 bank bit. Cartridge rules still apply, including mapper-specific treatment of bank zero. The example explicitly uses MBC5 banks 1–3; do not mix this state with untracked raw mapper writes.

Usage example

__farcall(3,callback);
bank_expect(callback_count==2 && callback_byte==0xD3,16);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

At this point in the complete program, __farcall raises callback_count to 2. The callback reads D3 from bank 3. A later near read of B2 from home2 verifies that execution returned with bank 2 mapped.

The complete program teaches how a bank number and near address identify data, how callbacks cross banks, and how to distinguish the library's record from the actual mapping. All displayed numbers are hexadecimal. BANK IN and BANK OUT must show 02, BYTE HEX D3, WORD HEX 5C7A, and both FAILED CHECKS and FIRST FAILURE 00. CGB and FC display blue text; DMG displays black text.

CALL COUNT is 03: far_call, __farcall and __farcall_ptr each invoke the callback once.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\banked_data_calls.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

if (funcName == "__farcall")
            {
                if (args.Length != 2) Program.Error("__farcall(bank, func) expects 2 arguments");
                if (!args[1].Match(Tag.Name, out string targetName)) Program.Error("__farcall(bank, func) requires 2nd argument to be a function name");

                // A named far call supplies no arguments. Reject data symbols
                // and callbacks that would otherwise read stale argument storage.
                CFunctionInfo targetInfo;
                if (!Functions.TryGetValue(targetName, out targetInfo))
                {
                    Error(expr, "__farcall requires a declared function name");
                    return;
                }
                if ((targetInfo.Parameters ?? Array.Empty<FieldInfo>()).Length != 0)
                {
                    Error(expr, "__farcall requires a callback with no parameters");
                    return;
                }
                Expr bankExpr = FoldConstants(args[0]);
                int targetBank = -1;
                if (targetInfo != null)
                {
                    targetBank = targetInfo.RomBank;
                    PrepareStructReturnDestination(expr, targetInfo.ReturnType, targetInfo, targetName);
                    if (targetInfo.ReturnType != null)
                        LastCallReturnsHL = ReturnsInHL(expr, targetInfo.ReturnType);
                }

                // A known bank permits direct dispatch when safe, otherwise request a fixed-bank thunk.
                if (TryResolveBankExprToConstU8(args[0], out int bankLiteral))
                {
                    int optimizedBank = bankLiteral & 0xFF;
                    bool farcallDirectOK = IsDirectCallBankSafe(optimizedBank, CurrentFunctionBank);
                    if (!farcallDirectOK)
                    {
                        string farcallThunkName = EnsureBank0Thunk(
                            targetName,
                            optimizedBank,
                            isStackCall: targetInfo != null && targetInfo.IsStackCall,
                            stackArgBytes: 0);
                        EmitAsm("CALL", new AsmOperand(farcallThunkName, AddressMode.Absolute));
                        RecordCallEdge(expr, targetName, optimizedBank, "farcall_bank_thunk", viaThunk: true, viaFarcall: true, actualArgSizes: new int[0], expectedArgSizes: new int[0]);
                    }
                    else
                    {
                        if (Program.CheckBankCalls && !InUnsafe && optimizedBank != 0)
                        {
                            AsmOperand ok = MakeUniqueLabel("kq_bank_ok");
                            EmitLoadA(RomBankVar);
                            EmitAsm("CP_IMM", new AsmOperand(optimizedBank & 0xFF, AddressMode.Immediate));
                            EmitAsm("JP_Z", ok);
                            EmitAsm("JP", EnsureCheckTrap());
                            EmitLabel(ok);
                        }

                        EmitAsm("CALL", new AsmOperand(targetName, AddressMode.Absolute));
                        RecordCallEdge(expr, targetName, optimizedBank, "farcall_direct", viaThunk: false, viaFarcall: true, actualArgSizes: new int[0], expectedArgSizes: new int[0]);
                    }
                    return;
                }

                // A = requested bank argument (runtime value)
                CompileIntoA(bankExpr);

                // Always dispatch via bank0 helper thunk.
                string thunkName = EnsureBank0RuntimeFarcallThunk(targetName);
                EmitAsm("CALL", new AsmOperand(thunkName, AddressMode.Absolute));
                RecordCallEdge(expr, targetName, targetBank, "farcall_intrinsic", viaThunk: true, viaFarcall: true, actualArgSizes: new int[0], expectedArgSizes: new int[0]);
                return;
            }

Read LCDC bit 6 to select the window tile-map base.

Syntax

u16 __getwinmapbase();

Return value

Returns $9800 or $9C00, the tile-map base rather than the tile graphics address.

Usage example

M_LCDC=0;result[2]=__getwinmapbase();M_LCDC=0x40;result[3]=__getwinmapbase();

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Learn map selection, scrolling, nesting and scanline waits. Bases are 38912/39936; nested tokens are 0/1; observed target LY values are 80/144. Also verify waits return with the LCD off.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch3_display.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch3_display.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --ramsize=none

if (funcName == "__getwinmapbase")
{
    if (args.Length != 0) Error(expr, "__getwinmapbase requires 0 arguments");

    AsmOperand win_base0 = MakeUniqueLabel("getwinbase_base0");
    AsmOperand win_done  = MakeUniqueLabel("getwinbase_done");

    EmitAsm("LDH_A_MEM", new AsmOperand(0x40, AddressMode.HighMem)); // LCDC
    EmitAsm("AND_IMM", new AsmOperand(0x40, AddressMode.Immediate)); // bit6 (Window tile map display select)
    EmitAsm("JR_Z", win_base0);
    EmitAsm("LD_HL_IMM", new AsmOperand(0x9C00, AddressMode.Immediate16));
    EmitAsm("JR", win_done);
    EmitLabel(win_base0);
    EmitAsm("LD_HL_IMM", new AsmOperand(0x9800, AddressMode.Immediate16));
    EmitLabel(win_done);
    LastCallReturnsHL = true;
    return;
}

Compute a unsigned multiply-accumulate.

Syntax

u16 __mac16(u16 acc, u16 a, u8 b);

Parameters

acc

16-bit accumulator to add.

a

Unsigned word, 0..65535.

b

Unsigned coefficient, 0..255.

Return value

Each term is floor(a*b/256), added to acc; returns the low 16 bits.

Conditions and limits

GB products are divided by 256; signed results truncate toward zero. Q1.7 variants double that truncated result and can differ by one from exact division by 128. Terms are rounded separately; final addition wraps at 16 bits.

Usage example

// Compare literal coefficients with values read from RAM.
result[34]=__mac16(65500,513,127);
v0=65500;v1=513;v2=127;
result[35]=__mac16(v0,v1,v2);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Compare literal inputs with values stored in RAM. Representative results appear as unsigned 16-bit values; negatives use two’s-complement bit patterns. GB rescales fixed-point products, while FC returns integer products, so identical inputs need not give identical results.

The excerpt stores these 16-bit values: result[34]=218, result[35]=218. Each literal-input calculation matches its RAM-input counterpart. The screen shows representative values; the result array holds every result.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch3_math.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch3_math.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --ramsize=none

if (funcName == "__mac16")
            {
                if (args.Length != 3) Error(expr, "__mac16 requires 3 arguments");

                // mul = (a*b)>>8
                EmitDotTermToHL(args[1], args[2], signed: false, q1_7: false, labelPrefix: "__mac16_mul");

                // acc + mul
                EmitAsm("PUSH_HL");
                CompileIntoHL(args[0]);
                EmitAsm("POP_DE");
                EmitAsm("ADD_HL_DE");
                LastCallReturnsHL = true;
                return;
            }

Compute a unsigned multiplication.

Syntax

u16 __mul16x8(u16 a, u8 b);

Parameters

a

Unsigned word, 0..65535.

b

Unsigned coefficient, 0..255.

Return value

Each term is floor(a*b/256); returns the low 16 bits.

Conditions and limits

GB products are divided by 256; signed results truncate toward zero. Q1.7 variants double that truncated result and can differ by one from exact division by 128. Terms are rounded separately; final addition wraps at 16 bits.

Usage example

// Compare literal coefficients with values read from RAM.
result[24]=__mul16x8(513,127);
v0=513;v1=127;
result[25]=__mul16x8(v0,v1);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Compare literal inputs with values stored in RAM. Representative results appear as unsigned 16-bit values; negatives use two’s-complement bit patterns. GB rescales fixed-point products, while FC returns integer products, so identical inputs need not give identical results.

The excerpt stores these 16-bit values: result[24]=254, result[25]=254. Each literal-input calculation matches its RAM-input counterpart. The screen shows representative values; the result array holds every result.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch3_math.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch3_math.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --ramsize=none

if (funcName == "__mul16x8")
            {
                if (args.Length != 2) Error(expr, "__mul16x8 requires 2 arguments");

                EmitDotTermToHL(args[0], args[1], signed: false, q1_7: false, labelPrefix: "__mul16x8");
                LastCallReturnsHL = true;
                return;
            }

Multiply two unsigned bytes and return the high byte.

Syntax

u8 __mul8x8_hi(u8 a, u8 b);

Parameters

a

Unsigned byte, 0..255.

b

Unsigned byte, 0..255.

Return value

floor(a*b/256), in 0..254.

Usage example

// Compare literal coefficients with values read from RAM.
result[4]=__mul8x8_hi(255,255);
v0=255;v1=255;
result[5]=__mul8x8_hi(v0,v1);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Compare literal inputs with values stored in RAM. Representative results appear as unsigned 16-bit values; negatives use two’s-complement bit patterns. GB rescales fixed-point products, while FC returns integer products, so identical inputs need not give identical results.

The excerpt stores these 16-bit values: result[4]=254, result[5]=254. Each literal-input calculation matches its RAM-input counterpart. The screen shows representative values; the result array holds every result.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch3_math.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch3_math.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --ramsize=none

if (funcName == "__mul8x8_hi")
            {
                if (args.Length != 2) Error(expr, "__mul8x8_hi requires 2 arguments");

                CompileIntoA(args[0]);
                EmitAsm("PUSH_AF");
                CompileIntoA(args[1]);
                EmitAsm("LD_C_A");
                EmitAsm("POP_AF");
                EmitAsm("LD_E_A");
                EmitMul8x8ToHL_EC("__mul8x8_hi");
                EmitAsm("LD_A_H");
                return;
            }

Schedule one repeating action selected by mask. Among newly pressed eligible bits, choose the lowest set bit and emit it immediately. Otherwise keep the active action while it remains eligible and held. If that action ends, adopt the lowest remaining held bit without an immediate pulse. No eligible held bits clears the runtime state.

Syntax

u8 __padrep(u8* state, u8 keys, u8 trigger, u8 mask);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

state

Pointer to five writable, consecutive RAM bytes, for example u8 state[5]. The layout is [0] active button bit, [1] initial delay, [2] repeat interval, [3] elapsed initial-delay count, [4] elapsed repeat count. Allocate a separate state for each independent scheduler. Initialize it before use; a null pointer, fewer than five bytes, or sharing the same state between directional and general schedulers is not supported.

keys

Current full held-button mask in the GB BTN_* layout. Supply a snapshot from __readpad, the low byte of __readpadex, or input_current; the scheduler does not poll hardware itself.

trigger

Newly pressed bits for this update in the same layout as keys, normally keys & ~previous_keys or the high byte of __readpadex. Only include bits also present in keys. Passing the held mask every time falsely restarts the initial press on every call.

mask

Eligible GB button bits combined with |. Zero disables all actions and clears the runtime state. Multiple bits enable several candidates, but the function emits only one selected bit per call, not a combined pulse mask.

Return value

Zero when no action pulse is due; otherwise one of 1, 2, 4, 8, 16, 32, 64, 128. The nonzero result is a button bit, not a normalized Boolean or a count of repeats.

Conditions and limits

Shared masks: BTN_RIGHT=0x01, BTN_LEFT=0x02, BTN_UP=0x04, BTN_DOWN=0x08, BTN_A=0x10, BTN_B=0x20, BTN_SELECT=0x40, BTN_START=0x80. A set bit means held. This layout applies to input_* on both GB and FC; raw FC pad functions use a different order.

Initial delay, 0–255 scheduler calls. With a positive value N, the first held repeat occurs exactly N calls after the initial press pulse. With 0, the initial-delay equality case is skipped and the repeat interval determines when the first held pulse occurs. These counts are not milliseconds.

Interval for subsequent repeats, 0–255 calls. Positive N emits every N eligible held updates after the first repeat. Zero emits on every eligible held update after the initial delay, so 0 and 1 both give one pulse per update at that stage. With both delay and interval set to 0, each held update emits a pulse.

Call the scheduler once per intended input tick. It modifies the state on every call and does not wait for VBlank. If a held button is adopted without a new-press bit, that adoption call returns 0 and starts a fresh delay. These functions schedule one active action per state; input_repeat instead maintains independent timers for all eight buttons.

Usage example

result=__padrep(actions,keys,trigger,48); // A|B: select A, the lower bit.
    if (result!=0) action_pulses++;

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This program feeds controlled button snapshots into four independent states to show exactly when a repeat fires. With delay 3 and interval 2, eight calls numbered 0–7 emit pulses on calls 0, 3, 5 and 7. RIGHT PULSES, DOWN PULSES, ACTION PULSES and ALIAS PULSES therefore each display 004. The general schedulers receive A and B together and select A (16). The program also checks initialization, reset, two-direction priority, release, adoption of an already held direction, zero timing values and an expression argument. CHECKS displays 057 and FAILED CHECKS must display 000. This is a deterministic state-processing example; it does not wait for you to press buttons.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\pad_repeat_state.c -I .\kitaq-docs\samples -I .\kitaqgb\lib -o .\out\pad_repeat_state.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

{
    if (args.Length != 4) Error(expr, "__padrep requires 4 arguments (state*, keys, trigger, mask)");

    AsmOperand pm_done        = MakeUniqueLabel("padrepM_done");
    AsmOperand pm_ret0        = MakeUniqueLabel("padrepM_ret0");
    AsmOperand pm_no_trig     = MakeUniqueLabel("padrepM_notrig");
    AsmOperand pm_reset_all   = MakeUniqueLabel("padrepM_reset");
    AsmOperand pm_dir0        = MakeUniqueLabel("padrepM_dir0");
    AsmOperand pm_have_dir    = MakeUniqueLabel("padrepM_havedir");
    AsmOperand pm_first_rep   = MakeUniqueLabel("padrepM_firstrep");
    AsmOperand pm_ret_dir     = MakeUniqueLabel("padrepM_retdir");
    AsmOperand pm_skip_dasinc = MakeUniqueLabel("padrepM_skipdasinc");
    AsmOperand pm_skip_arrinc = MakeUniqueLabel("padrepM_skiparrinc");

    // Evaluate args safely:
    // HL = state*, B = keys, C = trigger, E = mask
    CompileIntoHL(args[0]);
    EmitAsm("PUSH_HL");
    CompileIntoA(args[1]); EmitAsm("LD_B_A"); // keys
    CompileIntoA(args[2]); EmitAsm("LD_C_A"); // trigger
    CompileIntoA(args[3]); EmitAsm("LD_E_A"); // mask
    EmitAsm("POP_HL");

    // trigMasked = trigger & mask -> D
    EmitAsm("LD_A_C");
    EmitAsm("AND_E");
    EmitAsm("LD_D_A");
    EmitAsm("OR_A");
    EmitAsm("JP_Z", pm_no_trig);

    // select = lowbit(trigMasked) = x & -x
    EmitAsm("LD_A_D");
    EmitAsm("CPL");
    EmitAsm("INC_A");
    EmitAsm("AND_D");
    EmitAsm("LD_C_A"); // save selected in C

    // dirMask=selected, dasCnt=0, arrCnt=0
    EmitAsm("LD_A_C");
    EmitAsm("LD_HL_A"); // [0]=selected
    EmitAsm("PUSH_HL");
    EmitAsm("INC_HL"); Emi

Advance a repeat action for Down only. A new Down press returns 8 immediately and restarts the counters. Held Down produces later pulses according to the state's timing; releasing Down clears the runtime state. Other buttons do not trigger this scheduler.

Syntax

u8 __padrep_down(u8* state, u8 keys, u8 trigger);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

state

Pointer to five writable, consecutive RAM bytes, for example u8 state[5]. The layout is [0] active button bit, [1] initial delay, [2] repeat interval, [3] elapsed initial-delay count, [4] elapsed repeat count. Allocate a separate state for each independent scheduler. Initialize it before use; a null pointer, fewer than five bytes, or sharing the same state between directional and general schedulers is not supported.

keys

Current full held-button mask in the GB BTN_* layout. Supply a snapshot from __readpad, the low byte of __readpadex, or input_current; the scheduler does not poll hardware itself.

trigger

Newly pressed bits for this update in the same layout as keys, normally keys & ~previous_keys or the high byte of __readpadex. Only include bits also present in keys. Passing the held mask every time falsely restarts the initial press on every call.

Return value

Zero when no action pulse is due; otherwise one of 8. The nonzero result is a button bit, not a normalized Boolean or a count of repeats.

Conditions and limits

Shared masks: BTN_RIGHT=0x01, BTN_LEFT=0x02, BTN_UP=0x04, BTN_DOWN=0x08, BTN_A=0x10, BTN_B=0x20, BTN_SELECT=0x40, BTN_START=0x80. A set bit means held. This layout applies to input_* on both GB and FC; raw FC pad functions use a different order.

Initial delay, 0–255 scheduler calls. With a positive value N, the first held repeat occurs exactly N calls after the initial press pulse. With 0, the initial-delay equality case is skipped and the repeat interval determines when the first held pulse occurs. These counts are not milliseconds.

Interval for subsequent repeats, 0–255 calls. Positive N emits every N eligible held updates after the first repeat. Zero emits on every eligible held update after the initial delay, so 0 and 1 both give one pulse per update at that stage. With both delay and interval set to 0, each held update emits a pulse.

Call the scheduler once per intended input tick. It modifies the state on every call and does not wait for VBlank. If a held button is adopted without a new-press bit, that adoption call returns 0 and starts a fresh delay. These functions schedule one active action per state; input_repeat instead maintains independent timers for all eight buttons.

Usage example

result=__padrep_down(down,keys,trigger);
    if (result!=0) down_pulses++;

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This program feeds controlled button snapshots into four independent states to show exactly when a repeat fires. With delay 3 and interval 2, eight calls numbered 0–7 emit pulses on calls 0, 3, 5 and 7. RIGHT PULSES, DOWN PULSES, ACTION PULSES and ALIAS PULSES therefore each display 004. The general schedulers receive A and B together and select A (16). The program also checks initialization, reset, two-direction priority, release, adoption of an already held direction, zero timing values and an expression argument. CHECKS displays 057 and FAILED CHECKS must display 000. This is a deterministic state-processing example; it does not wait for you to press buttons.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\pad_repeat_state.c -I .\kitaq-docs\samples -I .\kitaqgb\lib -o .\out\pad_repeat_state.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

{
    if (args.Length != 3) Error(expr, "__padrep_down requires 3 arguments (state*, keys, trigger)");

    AsmOperand pd_done        = MakeUniqueLabel("padrepD_done");
    AsmOperand pd_ret0        = MakeUniqueLabel("padrepD_ret0");
    AsmOperand pd_no_trig     = MakeUniqueLabel("padrepD_notrig");
    AsmOperand pd_dir0        = MakeUniqueLabel("padrepD_dir0");
    AsmOperand pd_have_dir    = MakeUniqueLabel("padrepD_havedir");
    AsmOperand pd_first_rep   = MakeUniqueLabel("padrepD_firstrep");
    AsmOperand pd_ret_dir     = MakeUniqueLabel("padrepD_retdir");
    AsmOperand pd_skip_dasinc = MakeUniqueLabel("padrepD_skipdasinc");
    AsmOperand pd_skip_arrinc = MakeUniqueLabel("padrepD_skiparrinc");
    AsmOperand pd_reset_all   = MakeUniqueLabel("padrepD_reset");

    // Evaluate args safely:
    // HL = state*, B = keys, C = trigger
    CompileIntoHL(args[0]);
    EmitAsm("PUSH_HL");
    CompileIntoA(args[1]); EmitAsm("LD_B_A"); // keys
    CompileIntoA(args[2]); EmitAsm("LD_C_A"); // trigger
    EmitAsm("POP_HL");

    // --- Trigger Down? (bit3 = 0x08) ---
    EmitAsm("LD_A_C");
    EmitAsm("AND_IMM", new AsmOperand(0x08, AddressMode.Immediate));
    EmitAsm("JP_Z", pd_no_trig);

    // dirMask=0x08, dasCnt=0, arrCnt=0
    EmitAsm("LD_A_IMM", new AsmOperand(0x08, AddressMode.Immediate));
    EmitAsm("LD_HL_A"); // [0]=0x08
    EmitAsm("PUSH_HL");
    EmitAsm("INC_HL"); EmitAsm("INC_HL"); EmitAsm("INC_HL"); // -> [3]
    EmitAsm("XOR_A");
    EmitAsm("LD_HL_A"); // dasCnt=0
    EmitAsm("INC_HL");
    EmitAsm("LD_HL_A"); // arrCnt=0
    EmitAsm("POP_HL");

    EmitAsm

Initialize a caller-owned five-byte repeat state: clear the active action and both counters, and store the supplied initial delay and repeat interval. No buttons are read and no repeat pulse is emitted.

Syntax

void __padrep_init(u8* state, u8 das, u8 arr);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

state

Pointer to five writable, consecutive RAM bytes, for example u8 state[5]. The layout is [0] active button bit, [1] initial delay, [2] repeat interval, [3] elapsed initial-delay count, [4] elapsed repeat count. Allocate a separate state for each independent scheduler. Initialize it before use; a null pointer, fewer than five bytes, or sharing the same state between directional and general schedulers is not supported.

das

Initial delay, 0–255 scheduler calls. With a positive value N, the first held repeat occurs exactly N calls after the initial press pulse. With 0, the initial-delay equality case is skipped and the repeat interval determines when the first held pulse occurs. These counts are not milliseconds.

arr

Interval for subsequent repeats, 0–255 calls. Positive N emits every N eligible held updates after the first repeat. Zero emits on every eligible held update after the initial delay, so 0 and 1 both give one pulse per update at that stage. With both delay and interval set to 0, each held update emits a pulse.

Return value

None (void).

Usage example

__padrep_init(lr,3,2);
// Active action and counters are zero; delay and interval are retained.
expect(lr[0],0); expect(lr[1],3); expect(lr[2],2);
expect(lr[3],0); expect(lr[4],0);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This program feeds controlled button snapshots into four independent states to show exactly when a repeat fires. With delay 3 and interval 2, eight calls numbered 0–7 emit pulses on calls 0, 3, 5 and 7. RIGHT PULSES, DOWN PULSES, ACTION PULSES and ALIAS PULSES therefore each display 004. The general schedulers receive A and B together and select A (16). The program also checks initialization, reset, two-direction priority, release, adoption of an already held direction, zero timing values and an expression argument. CHECKS displays 057 and FAILED CHECKS must display 000. This is a deterministic state-processing example; it does not wait for you to press buttons.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\pad_repeat_state.c -I .\kitaq-docs\samples -I .\kitaqgb\lib -o .\out\pad_repeat_state.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

{
    if (args.Length != 3) Error(expr, "__padrep_init requires 3 arguments (state*, das, arr)");

    // Evaluate args with register safety
    CompileIntoHL(args[0]);
    EmitAsm("PUSH_HL");
    CompileIntoA(args[1]); EmitAsm("LD_B_A"); // das
    CompileIntoA(args[2]); EmitAsm("LD_C_A"); // arr
    EmitAsm("POP_HL");

    // dirMask = 0; dasCnt=0; arrCnt=0; store params
    EmitAsm("XOR_A");
    EmitAsm("LD_HL_A"); // [0]=0
    EmitAsm("INC_HL");
    EmitAsm("LD_A_B");
    EmitAsm("LD_HL_A"); // [1]=das
    EmitAsm("INC_HL");
    EmitAsm("LD_A_C");
    EmitAsm("LD_HL_A"); // [2]=arr
    EmitAsm("INC_HL");
    EmitAsm("XOR_A");
    EmitAsm("LD_HL_A"); // [3]=dasCnt
    EmitAsm("INC_HL");
    EmitAsm("LD_HL_A"); // [4]=arrCnt
    return;
}

// 2.21 __padrep_reset(state_ptr) -> void
// Resets runtime counters for PadRepeatState while keeping das/arr params:
// dirMask=0, dasCnt=0, arrCnt=0
// Treated as a compiler intrinsic (no C definition required).
if (funcName == "__padrep_reset")
{
    if (args.Length != 1) Error(expr, "__padrep_reset requires 1 argument (state*)");

    CompileIntoHL(args[0]);

    EmitAsm("XOR_A");
    EmitAsm("LD_HL_A"); // [0]=0 (dirMask)

    // [3]=0, [4]=0
    EmitAsm("PUSH_HL");
    EmitAsm("INC_HL"); EmitAsm("INC_HL"); EmitAsm("INC_HL"); // -> [3]
    EmitAsm("LD_HL_A");
    EmitAsm("INC_HL"); // -> [4]
    EmitAsm("LD_HL_A");
    EmitAsm("POP_HL");
    return;
}

// __padrep_lr(state*, keys, trigger) returns Right (1), Left (2), or zero.
// New triggers take priority, with Right selected first when both trigger bits are set.
// Without a new

Advance a single Left/Right repeat action. A new Right press emits 1 immediately; otherwise a new Left press emits 2. If both are newly pressed, Right wins. Without a new press, holding both directions returns 0 and freezes the counters; holding neither clears the runtime state.

Syntax

u8 __padrep_lr(u8* state, u8 keys, u8 trigger);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

state

Pointer to five writable, consecutive RAM bytes, for example u8 state[5]. The layout is [0] active button bit, [1] initial delay, [2] repeat interval, [3] elapsed initial-delay count, [4] elapsed repeat count. Allocate a separate state for each independent scheduler. Initialize it before use; a null pointer, fewer than five bytes, or sharing the same state between directional and general schedulers is not supported.

keys

Current full held-button mask in the GB BTN_* layout. Supply a snapshot from __readpad, the low byte of __readpadex, or input_current; the scheduler does not poll hardware itself.

trigger

Newly pressed bits for this update in the same layout as keys, normally keys & ~previous_keys or the high byte of __readpadex. Only include bits also present in keys. Passing the held mask every time falsely restarts the initial press on every call.

Return value

Zero when no action pulse is due; otherwise one of 1, 2. The nonzero result is a button bit, not a normalized Boolean or a count of repeats.

Conditions and limits

Shared masks: BTN_RIGHT=0x01, BTN_LEFT=0x02, BTN_UP=0x04, BTN_DOWN=0x08, BTN_A=0x10, BTN_B=0x20, BTN_SELECT=0x40, BTN_START=0x80. A set bit means held. This layout applies to input_* on both GB and FC; raw FC pad functions use a different order.

Initial delay, 0–255 scheduler calls. With a positive value N, the first held repeat occurs exactly N calls after the initial press pulse. With 0, the initial-delay equality case is skipped and the repeat interval determines when the first held pulse occurs. These counts are not milliseconds.

Interval for subsequent repeats, 0–255 calls. Positive N emits every N eligible held updates after the first repeat. Zero emits on every eligible held update after the initial delay, so 0 and 1 both give one pulse per update at that stage. With both delay and interval set to 0, each held update emits a pulse.

Call the scheduler once per intended input tick. It modifies the state on every call and does not wait for VBlank. If a held button is adopted without a new-press bit, that adoption call returns 0 and starts a fresh delay. These functions schedule one active action per state; input_repeat instead maintains independent timers for all eight buttons.

Usage example

result=__padrep_lr(lr,keys,trigger);
    if (result!=0) pulses++;

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This program feeds controlled button snapshots into four independent states to show exactly when a repeat fires. With delay 3 and interval 2, eight calls numbered 0–7 emit pulses on calls 0, 3, 5 and 7. RIGHT PULSES, DOWN PULSES, ACTION PULSES and ALIAS PULSES therefore each display 004. The general schedulers receive A and B together and select A (16). The program also checks initialization, reset, two-direction priority, release, adoption of an already held direction, zero timing values and an expression argument. CHECKS displays 057 and FAILED CHECKS must display 000. This is a deterministic state-processing example; it does not wait for you to press buttons.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\pad_repeat_state.c -I .\kitaq-docs\samples -I .\kitaqgb\lib -o .\out\pad_repeat_state.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

{
    if (args.Length != 3) Error(expr, "__padrep_lr requires 3 arguments (state*, keys, trigger)");

    AsmOperand pr_done        = MakeUniqueLabel("padrep_done");
    AsmOperand pr_ret0        = MakeUniqueLabel("padrep_ret0");
    AsmOperand pr_check_left  = MakeUniqueLabel("padrep_chkL");
    AsmOperand pr_no_trig     = MakeUniqueLabel("padrep_notrig");
    AsmOperand pr_reset_all   = MakeUniqueLabel("padrep_reset");
    AsmOperand pr_dir0        = MakeUniqueLabel("padrep_dir0");
    AsmOperand pr_have_dir    = MakeUniqueLabel("padrep_havedir");
    AsmOperand pr_first_rep   = MakeUniqueLabel("padrep_firstrep");
    AsmOperand pr_ret_dir     = MakeUniqueLabel("padrep_retdir");
    AsmOperand pr_skip_dasinc = MakeUniqueLabel("padrep_skipdasinc");
    AsmOperand pr_skip_arrinc = MakeUniqueLabel("padrep_skiparrinc");

    // Evaluate args safely:
    // HL = state*, B = keys, C = trigger
    CompileIntoHL(args[0]);
    EmitAsm("PUSH_HL");
    CompileIntoA(args[1]); EmitAsm("LD_B_A"); // keys
    CompileIntoA(args[2]); EmitAsm("LD_C_A"); // trigger
    EmitAsm("POP_HL");

    // --- Trigger Right? (bit0) ---
    EmitAsm("LD_A_C");
    EmitAsm("AND_IMM", new AsmOperand(0x01, AddressMode.Immediate));
    EmitAsm("JP_Z", pr_check_left);

    // dirMask=0x01, dasCnt=0, arrCnt=0
    EmitAsm("LD_A_IMM", new AsmOperand(0x01, AddressMode.Immediate));
    EmitAsm("LD_HL_A"); // [0]=0x01
    EmitAsm("PUSH_HL");
    EmitAsm("INC_HL"); EmitAsm("INC_HL"); EmitAsm("INC_HL"); // -> [3]
    EmitAsm("XOR_A");
    EmitAsm("LD_HL_A"); // dasCnt=0
    EmitAsm("INC_HL");
    EmitAsm("LD_HL_A")

__padrep_mask is an alternative spelling of __padrep; both enter the same compiler implementation. It has the same single-action selection, timing, state layout and return values. The explicit name can make a masked action scheduler easier to recognize at a call site.

Schedule one repeating action selected by mask. Among newly pressed eligible bits, choose the lowest set bit and emit it immediately. Otherwise keep the active action while it remains eligible and held. If that action ends, adopt the lowest remaining held bit without an immediate pulse. No eligible held bits clears the runtime state.

Syntax

u8 __padrep_mask(u8* state, u8 keys, u8 trigger, u8 mask);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

state

Pointer to five writable, consecutive RAM bytes, for example u8 state[5]. The layout is [0] active button bit, [1] initial delay, [2] repeat interval, [3] elapsed initial-delay count, [4] elapsed repeat count. Allocate a separate state for each independent scheduler. Initialize it before use; a null pointer, fewer than five bytes, or sharing the same state between directional and general schedulers is not supported.

keys

Current full held-button mask in the GB BTN_* layout. Supply a snapshot from __readpad, the low byte of __readpadex, or input_current; the scheduler does not poll hardware itself.

trigger

Newly pressed bits for this update in the same layout as keys, normally keys & ~previous_keys or the high byte of __readpadex. Only include bits also present in keys. Passing the held mask every time falsely restarts the initial press on every call.

mask

Eligible GB button bits combined with |. Zero disables all actions and clears the runtime state. Multiple bits enable several candidates, but the function emits only one selected bit per call, not a combined pulse mask.

Return value

Zero when no action pulse is due; otherwise one of 1, 2, 4, 8, 16, 32, 64, 128. The nonzero result is a button bit, not a normalized Boolean or a count of repeats.

Conditions and limits

Shared masks: BTN_RIGHT=0x01, BTN_LEFT=0x02, BTN_UP=0x04, BTN_DOWN=0x08, BTN_A=0x10, BTN_B=0x20, BTN_SELECT=0x40, BTN_START=0x80. A set bit means held. This layout applies to input_* on both GB and FC; raw FC pad functions use a different order.

Initial delay, 0–255 scheduler calls. With a positive value N, the first held repeat occurs exactly N calls after the initial press pulse. With 0, the initial-delay equality case is skipped and the repeat interval determines when the first held pulse occurs. These counts are not milliseconds.

Interval for subsequent repeats, 0–255 calls. Positive N emits every N eligible held updates after the first repeat. Zero emits on every eligible held update after the initial delay, so 0 and 1 both give one pulse per update at that stage. With both delay and interval set to 0, each held update emits a pulse.

Call the scheduler once per intended input tick. It modifies the state on every call and does not wait for VBlank. If a held button is adopted without a new-press bit, that adoption call returns 0 and starts a fresh delay. These functions schedule one active action per state; input_repeat instead maintains independent timers for all eight buttons.

Usage example

result=__padrep_mask(alias_state,keys,trigger,48);
    if (result!=0) alias_pulses++;

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This program feeds controlled button snapshots into four independent states to show exactly when a repeat fires. With delay 3 and interval 2, eight calls numbered 0–7 emit pulses on calls 0, 3, 5 and 7. RIGHT PULSES, DOWN PULSES, ACTION PULSES and ALIAS PULSES therefore each display 004. The general schedulers receive A and B together and select A (16). The program also checks initialization, reset, two-direction priority, release, adoption of an already held direction, zero timing values and an expression argument. CHECKS displays 057 and FAILED CHECKS must display 000. This is a deterministic state-processing example; it does not wait for you to press buttons.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\pad_repeat_state.c -I .\kitaq-docs\samples -I .\kitaqgb\lib -o .\out\pad_repeat_state.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

{
    if (args.Length != 4) Error(expr, "__padrep requires 4 arguments (state*, keys, trigger, mask)");

    AsmOperand pm_done        = MakeUniqueLabel("padrepM_done");
    AsmOperand pm_ret0        = MakeUniqueLabel("padrepM_ret0");
    AsmOperand pm_no_trig     = MakeUniqueLabel("padrepM_notrig");
    AsmOperand pm_reset_all   = MakeUniqueLabel("padrepM_reset");
    AsmOperand pm_dir0        = MakeUniqueLabel("padrepM_dir0");
    AsmOperand pm_have_dir    = MakeUniqueLabel("padrepM_havedir");
    AsmOperand pm_first_rep   = MakeUniqueLabel("padrepM_firstrep");
    AsmOperand pm_ret_dir     = MakeUniqueLabel("padrepM_retdir");
    AsmOperand pm_skip_dasinc = MakeUniqueLabel("padrepM_skipdasinc");
    AsmOperand pm_skip_arrinc = MakeUniqueLabel("padrepM_skiparrinc");

    // Evaluate args safely:
    // HL = state*, B = keys, C = trigger, E = mask
    CompileIntoHL(args[0]);
    EmitAsm("PUSH_HL");
    CompileIntoA(args[1]); EmitAsm("LD_B_A"); // keys
    CompileIntoA(args[2]); EmitAsm("LD_C_A"); // trigger
    CompileIntoA(args[3]); EmitAsm("LD_E_A"); // mask
    EmitAsm("POP_HL");

    // trigMasked = trigger & mask -> D
    EmitAsm("LD_A_C");
    EmitAsm("AND_E");
    EmitAsm("LD_D_A");
    EmitAsm("OR_A");
    EmitAsm("JP_Z", pm_no_trig);

    // select = lowbit(trigMasked) = x & -x
    EmitAsm("LD_A_D");
    EmitAsm("CPL");
    EmitAsm("INC_A");
    EmitAsm("AND_D");
    EmitAsm("LD_C_A"); // save selected in C

    // dirMask=selected, dasCnt=0, arrCnt=0
    EmitAsm("LD_A_C");
    EmitAsm("LD_HL_A"); // [0]=selected
    EmitAsm("PUSH_HL");
    EmitAsm("INC_HL"); Emi

Cancel the active action and clear both elapsed counters while preserving the configured delay and interval. Use this when closing a menu or changing input focus so a previous hold does not carry its repeat timing into the next interaction.

Syntax

void __padrep_reset(u8* state);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

state

Pointer to five writable, consecutive RAM bytes, for example u8 state[5]. The layout is [0] active button bit, [1] initial delay, [2] repeat interval, [3] elapsed initial-delay count, [4] elapsed repeat count. Allocate a separate state for each independent scheduler. Initialize it before use; a null pointer, fewer than five bytes, or sharing the same state between directional and general schedulers is not supported.

Return value

None (void).

Usage example

__padrep_reset(lr);
expect(lr[0],0); expect(lr[1],3); expect(lr[2],2);
expect(lr[3],0); expect(lr[4],0);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This program feeds controlled button snapshots into four independent states to show exactly when a repeat fires. With delay 3 and interval 2, eight calls numbered 0–7 emit pulses on calls 0, 3, 5 and 7. RIGHT PULSES, DOWN PULSES, ACTION PULSES and ALIAS PULSES therefore each display 004. The general schedulers receive A and B together and select A (16). The program also checks initialization, reset, two-direction priority, release, adoption of an already held direction, zero timing values and an expression argument. CHECKS displays 057 and FAILED CHECKS must display 000. This is a deterministic state-processing example; it does not wait for you to press buttons.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\pad_repeat_state.c -I .\kitaq-docs\samples -I .\kitaqgb\lib -o .\out\pad_repeat_state.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

{
    if (args.Length != 1) Error(expr, "__padrep_reset requires 1 argument (state*)");

    CompileIntoHL(args[0]);

    EmitAsm("XOR_A");
    EmitAsm("LD_HL_A"); // [0]=0 (dirMask)

    // [3]=0, [4]=0
    EmitAsm("PUSH_HL");
    EmitAsm("INC_HL"); EmitAsm("INC_HL"); EmitAsm("INC_HL"); // -> [3]
    EmitAsm("LD_HL_A");
    EmitAsm("INC_HL"); // -> [4]
    EmitAsm("LD_HL_A");
    EmitAsm("POP_HL");
    return;
}

// __padrep_lr(state*, keys, trigger) returns Right (1), Left (2), or zero.
// New triggers take priority, with Right selected first when both trigger bits are set.
// Without a new trigger, simultaneous Left/Right holds suppress movement without resetting counters.
// A single held direction is adopted without immediate movement when no direction is active.
// Subsequent updates use the five-byte state's initial delay and repeat interval; ARR=0 repeats each update.
if (funcName == "__padrep_lr")
{
    if (args.Length != 3) Error(expr, "__padrep_lr requires 3 arguments (state*, keys, trigger)");

    AsmOperand pr_done        = MakeUniqueLabel("padrep_done");
    AsmOperand pr_ret0        = MakeUniqueLabel("padrep_ret0");
    AsmOperand pr_check_left  = MakeUniqueLabel("padrep_chkL");
    AsmOperand pr_no_trig     = MakeUniqueLabel("padrep_notrig");
    AsmOperand pr_reset_all   = MakeUniqueLabel("padrep_reset");
    AsmOperand pr_dir0        = MakeUniqueLabel("padrep_dir0");
    AsmOperand pr_have_dir    = MakeUniqueLabel("padrep_havedir");
    AsmOperand pr_first_rep   = MakeUniqueLabel("padrep_firstrep");
    AsmOperand pr_ret_dir     = MakeUniqueLabel("padrep

Read directions and action buttons from JOYP and combine them into the shared 8-bit button mask. Selects each JOYP group, performs two reads for settling, then restores the group-selection bits to 0x30.

Syntax

u8 __readpad();

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Return value

An 8-bit mask in the shared BTN_* layout. Several buttons may be set simultaneously; 0 means none.

Conditions and limits

Shared masks: BTN_RIGHT=0x01, BTN_LEFT=0x02, BTN_UP=0x04, BTN_DOWN=0x08, BTN_A=0x10, BTN_B=0x20, BTN_SELECT=0x40, BTN_START=0x80. A set bit means held. This layout applies to input_* on both GB and FC; raw FC pad functions use a different order.

This call reads a fresh hardware snapshot; it does not update input_* or nes_pad1_* cached state and does not generate pressed/released edges or repeats. Read once, save the result, and derive edges against your saved previous mask when needed.

Usage example

all_keys=__readpad(); // A + Right: 0x11, decimal 17.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Use this program to compare the three button-mask layouts and the packed press result. Hold A and Right together. ALL KEYS is 17; DIRECTIONS and BUTTONS LOW are each 1. With a previous mask of 0, EX CURRENT and EX NEW PRESS are both 17. Passing the current mask to the next read makes HELD PRESS 0. FAILED CHECKS must be 0. The values remain on screen after the snapshot, so releasing the buttons does not erase them.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\input_raw.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\input_raw.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm --no-cache

{
    if (args.Length != 0) Error(expr, "__readpad requires 0 arguments");

    AsmOperand p1 = new AsmOperand(0x00, AddressMode.HighMem); // P1 / JOYP

    // Directions (P1=0x20)
    EmitAsm("LD_A_IMM", new AsmOperand(0x20, AddressMode.Immediate));
    EmitAsm("LDH_MEM_A", p1);
    EmitAsm("LDH_A_MEM", p1); // dummy reads for settle
    EmitAsm("LDH_A_MEM", p1);
    EmitAsm("CPL");
    EmitAsm("AND_IMM", new AsmOperand(0x0F, AddressMode.Immediate));
    EmitAsm("LD_C_A"); // dpad in C

    // Buttons (P1=0x10)
    EmitAsm("LD_A_IMM", new AsmOperand(0x10, AddressMode.Immediate));
    EmitAsm("LDH_MEM_A", p1);
    EmitAsm("LDH_A_MEM", p1);
    EmitAsm("LDH_A_MEM", p1);
    EmitAsm("CPL");
    EmitAsm("AND_IMM", new AsmOperand(0x0F, AddressMode.Immediate));
    // shift into upper nibble (<<4)
    EmitAsm("RLCA"); EmitAsm("RLCA"); EmitAsm("RLCA"); EmitAsm("RLCA");
    EmitAsm("OR_C");

    // Restore P1 selection (0x30) without losing return value
    EmitAsm("LD_C_A");
    EmitAsm("LD_A_IMM", new AsmOperand(0x30, AddressMode.Immediate));
    EmitAsm("LDH_MEM_A", p1);
    EmitAsm("LD_A_C");
    return;
}

// 2.17 __readpaddir() -> u8 in A (bits0..3 only)
// Returns dpad nibble (Right,Left,Up,Down) with 1 when pressed.
// Treated as a compiler intrinsic (no C definition required).
if (funcName == "__readpaddir")
{
    if (args.Length != 0) Error(expr, "__readpaddir requires 0 arguments");

    AsmOperand p1 = new AsmOperand(0x00, AddressMode.HighMem); // P1 / JOYP

    EmitAsm("LD_A_IMM", new AsmOperand(0x20, AddressMode.Immediate));
    EmitAsm("LDH_MEM_A", p1);
    EmitAsm

Read only the JOYP action-button group as a low nibble: A=1, B=2, Select=4, Start=8. These values are not BTN_A through BTN_START; those shared masks occupy the high nibble. JOYP selection is restored to 0x30.

Syntax

u8 __readpadbtn();

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Return value

A mask from 0 to 15 in the bit order described above. More than one bit can be set; test a button with result & bit, rather than comparing the whole result to 1.

Conditions and limits

This call reads a fresh hardware snapshot; it does not update input_* or nes_pad1_* cached state and does not generate pressed/released edges or repeats. Read once, save the result, and derive edges against your saved previous mask when needed.

Usage example

buttons=__readpadbtn(); // A: 1, not BTN_A (16).

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Use this program to compare the three button-mask layouts and the packed press result. Hold A and Right together. ALL KEYS is 17; DIRECTIONS and BUTTONS LOW are each 1. With a previous mask of 0, EX CURRENT and EX NEW PRESS are both 17. Passing the current mask to the next read makes HELD PRESS 0. FAILED CHECKS must be 0. The values remain on screen after the snapshot, so releasing the buttons does not erase them.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\input_raw.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\input_raw.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm --no-cache

{
    if (args.Length != 0) Error(expr, "__readpadbtn requires 0 arguments");

    AsmOperand p1 = new AsmOperand(0x00, AddressMode.HighMem); // P1 / JOYP

    EmitAsm("LD_A_IMM", new AsmOperand(0x10, AddressMode.Immediate));
    EmitAsm("LDH_MEM_A", p1);
    EmitAsm("LDH_A_MEM", p1);
    EmitAsm("LDH_A_MEM", p1);
    EmitAsm("CPL");
    EmitAsm("AND_IMM", new AsmOperand(0x0F, AddressMode.Immediate));

    EmitAsm("LD_C_A");
    EmitAsm("LD_A_IMM", new AsmOperand(0x30, AddressMode.Immediate));
    EmitAsm("LDH_MEM_A", p1);
    EmitAsm("LD_A_C");
    return;
}

// 2.19 __readpadex(prev_u8) -> u16 in HL
// Returns: L = keys (same encoding as __readpad), H = trigger (newly pressed edge: keys & ~prev).
// This mirrors the common pattern:
// prev = keys; keys = __readpad(); trigger = keys & ~prev;
// Treated as a compiler intrinsic (no C definition required).
if (funcName == "__readpadex")
{
    if (args.Length != 1) Error(expr, "__readpadex requires 1 argument (prev_keys)");

    // prev -> B
    CompileIntoA(args[0]);
    EmitAsm("LD_B_A");

    AsmOperand p1 = new AsmOperand(0x00, AddressMode.HighMem); // P1 / JOYP

    // Directions (P1=0x20)
    EmitAsm("LD_A_IMM", new AsmOperand(0x20, AddressMode.Immediate));
    EmitAsm("LDH_MEM_A", p1);
    EmitAsm("LDH_A_MEM", p1);
    EmitAsm("LDH_A_MEM", p1);
    EmitAsm("CPL");
    EmitAsm("AND_IMM", new AsmOperand(0x0F, AddressMode.Immediate));
    EmitAsm("LD_C_A"); // dpad in C

    // Buttons (P1=0x10)
    EmitAsm("LD_A_IMM", new AsmOperand(0x10, AddressMode.Immediate));
    EmitAsm("LDH_MEM_A", p1);
    EmitAsm("LDH_A_MEM", p1)

Read only the JOYP direction group. The result uses bits 0–3: Right=1, Left=2, Up=4, Down=8; bits 4–7 are zero. Action buttons are ignored and JOYP selection is restored to 0x30.

Syntax

u8 __readpaddir();

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Return value

A mask from 0 to 15 in the bit order described above. More than one bit can be set; test a button with result & bit, rather than comparing the whole result to 1.

Conditions and limits

This call reads a fresh hardware snapshot; it does not update input_* or nes_pad1_* cached state and does not generate pressed/released edges or repeats. Read once, save the result, and derive edges against your saved previous mask when needed.

Usage example

directions=__readpaddir(); // Right: 1. The held A button is not included.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Use this program to compare the three button-mask layouts and the packed press result. Hold A and Right together. ALL KEYS is 17; DIRECTIONS and BUTTONS LOW are each 1. With a previous mask of 0, EX CURRENT and EX NEW PRESS are both 17. Passing the current mask to the next read makes HELD PRESS 0. FAILED CHECKS must be 0. The values remain on screen after the snapshot, so releasing the buttons does not erase them.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\input_raw.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\input_raw.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm --no-cache

{
    if (args.Length != 0) Error(expr, "__readpaddir requires 0 arguments");

    AsmOperand p1 = new AsmOperand(0x00, AddressMode.HighMem); // P1 / JOYP

    EmitAsm("LD_A_IMM", new AsmOperand(0x20, AddressMode.Immediate));
    EmitAsm("LDH_MEM_A", p1);
    EmitAsm("LDH_A_MEM", p1);
    EmitAsm("LDH_A_MEM", p1);
    EmitAsm("CPL");
    EmitAsm("AND_IMM", new AsmOperand(0x0F, AddressMode.Immediate));

    EmitAsm("LD_C_A");
    EmitAsm("LD_A_IMM", new AsmOperand(0x30, AddressMode.Immediate));
    EmitAsm("LDH_MEM_A", p1);
    EmitAsm("LD_A_C");
    return;
}

// 2.18 __readpadbtn() -> u8 in A (bits0..3 only)
// Returns buttons nibble (A,B,Select,Start) with 1 when pressed.
// Treated as a compiler intrinsic (no C definition required).
if (funcName == "__readpadbtn")
{
    if (args.Length != 0) Error(expr, "__readpadbtn requires 0 arguments");

    AsmOperand p1 = new AsmOperand(0x00, AddressMode.HighMem); // P1 / JOYP

    EmitAsm("LD_A_IMM", new AsmOperand(0x10, AddressMode.Immediate));
    EmitAsm("LDH_MEM_A", p1);
    EmitAsm("LDH_A_MEM", p1);
    EmitAsm("LDH_A_MEM", p1);
    EmitAsm("CPL");
    EmitAsm("AND_IMM", new AsmOperand(0x0F, AddressMode.Immediate));

    EmitAsm("LD_C_A");
    EmitAsm("LD_A_IMM", new AsmOperand(0x30, AddressMode.Immediate));
    EmitAsm("LDH_MEM_A", p1);
    EmitAsm("LD_A_C");
    return;
}

// 2.19 __readpadex(prev_u8) -> u16 in HL
// Returns: L = keys (same encoding as __readpad), H = trigger (newly pressed edge: keys & ~prev).
// This mirrors the common pattern:
// prev = keys; keys = __readpad(); trigger = keys & ~prev;
// Treated as a c

Compute a signed two-term dot product.

Syntax

u16 __sdot2_q1_7(u16 a0, u16 a1, u8 b0, u8 b1);

Parameters

a0

Signed 16-bit bit pattern, representing −32768..32767.

a1

Signed 16-bit bit pattern, representing −32768..32767.

b0

Signed byte bit pattern, coefficient −128..127.

b1

Signed byte bit pattern, coefficient −128..127.

Return value

Each term is 2*trunc(a*b/256). Sum the terms; returns the low 16 bits.

Conditions and limits

GB products are divided by 256; signed results truncate toward zero. Q1.7 variants double that truncated result and can differ by one from exact division by 128. Terms are rounded separately; final addition wraps at 16 bits.

Usage example

// Compare literal coefficients with values read from RAM.
result[20]=__sdot2_q1_7(-513,769,-64,127);
v0=-513;v1=769;v2=-64;v3=127;
result[21]=__sdot2_q1_7(v0,v1,v2,v3);
// Reverse coefficient signs and verify negative products.
result[22]=__sdot2_q1_7(-513,769,64,-127);
v0=-513;v1=769;v2=64;v3=-127;
result[23]=__sdot2_q1_7(v0,v1,v2,v3);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Compare literal inputs with values stored in RAM. Representative results appear as unsigned 16-bit values; negatives use two’s-complement bit patterns. GB rescales fixed-point products, while FC returns integer products, so identical inputs need not give identical results.

The excerpt stores these 16-bit values: result[20]=1018, result[21]=1018, result[22]=64518, result[23]=64518. Each literal-input calculation matches its RAM-input counterpart. The screen shows representative values; the result array holds every result.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch3_math.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch3_math.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --ramsize=none

if (funcName == "__sdot2_q1_7")
{
    if (args.Length != 4) Error(expr, "__sdot2_q1_7 requires 4 arguments");
    LastCallReturnsHL = true;

    // x*ax
    if (!TryEmitDot2Pow2Term(args[0], args[2], signed: true, q1_7: true, out _))
    {
        CompileIntoHL(args[0]);
        EmitAsm("PUSH_HL");
        CompileIntoA(args[2]);
        EmitAsm("LD_C_A");
        EmitAsm("POP_HL");
        EmitSMul16x8Shr8_HL("__sdot2_q1_7_x");
        EmitAsm("ADD_HL_HL");
    }
    EmitAsm("PUSH_HL");

    // y*ay
    if (!TryEmitDot2Pow2Term(args[1], args[3], signed: true, q1_7: true, out _))
    {
        CompileIntoHL(args[1]);
        EmitAsm("PUSH_HL");
        CompileIntoA(args[3]);
        EmitAsm("LD_C_A");
        EmitAsm("POP_HL");
        EmitSMul16x8Shr8_HL("__sdot2_q1_7_y");
        EmitAsm("ADD_HL_HL");
    }
    EmitAsm("POP_DE");
    EmitAsm("ADD_HL_DE");
    return;
}

Compute a signed two-term dot product.

Syntax

u16 __sdot2_q8_8(u16 a0, u16 a1, u8 b0, u8 b1);

Parameters

a0

Signed 16-bit bit pattern, representing −32768..32767.

a1

Signed 16-bit bit pattern, representing −32768..32767.

b0

Signed byte bit pattern, coefficient −128..127.

b1

Signed byte bit pattern, coefficient −128..127.

Return value

Each term is trunc(a*b/256). Sum the terms; returns the low 16 bits.

Conditions and limits

GB products are divided by 256; signed results truncate toward zero. Q1.7 variants double that truncated result and can differ by one from exact division by 128. Terms are rounded separately; final addition wraps at 16 bits.

Usage example

// Compare literal coefficients with values read from RAM.
result[30]=__sdot2_q8_8(-513,769,-64,127);
v0=-513;v1=769;v2=-64;v3=127;
result[31]=__sdot2_q8_8(v0,v1,v2,v3);
// Reverse coefficient signs and verify negative products.
result[32]=__sdot2_q8_8(-513,769,64,-127);
v0=-513;v1=769;v2=64;v3=-127;
result[33]=__sdot2_q8_8(v0,v1,v2,v3);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Compare literal inputs with values stored in RAM. Representative results appear as unsigned 16-bit values; negatives use two’s-complement bit patterns. GB rescales fixed-point products, while FC returns integer products, so identical inputs need not give identical results.

The excerpt stores these 16-bit values: result[30]=509, result[31]=509, result[32]=65027, result[33]=65027. Each literal-input calculation matches its RAM-input counterpart. The screen shows representative values; the result array holds every result.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch3_math.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch3_math.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --ramsize=none

if (funcName == "__sdot2_q8_8")
{
    if (args.Length != 4) Error(expr, "__sdot2_q8_8 requires 4 arguments");
    LastCallReturnsHL = true;

    // Fast paths when coefficients are compile-time constants.
    // Special-case: 0 / power-of-two coefficients (s8 two's complement) => arithmetic shift instead of mul.
    if (TryGetS8Const(args[2], out int sax0) && (sax0 == 0) && TryGetS8Const(args[3], out int say0) && (say0 == 0))
    {
        CompileDiscard(args[0]);
        CompileDiscard(args[1]);
        EmitAsm("XOR_A");
        EmitAsm("LD_H_A");
        EmitAsm("LD_L_A");
        return;
    }
    if (TryGetS8Const(args[2], out int saxOnly) && (saxOnly == 0))
    {
        CompileDiscard(args[0]);
        // only y*ay
        if (!TryEmitDot2Pow2Term(args[1], args[3], signed: true, q1_7: false, out _))
        {
            CompileIntoHL(args[1]);
            EmitAsm("PUSH_HL");
            CompileIntoA(args[3]);
            EmitAsm("LD_C_A");
            EmitAsm("POP_HL");
            EmitSMul16x8Shr8_HL("__sdot2_y");
        }
        return;
    }
    if (TryGetS8Const(args[3], out int sayOnly) && (sayOnly == 0))
    {
        // only x*ax
        if (!TryEmitDot2Pow2Term(args[0], args[2], signed: true, q1_7: false, out _))
        {
            CompileIntoHL(args[0]);
            EmitAsm("PUSH_HL");
            CompileIntoA(args[2]);
            EmitAsm("LD_C_A");
            EmitAsm("POP_HL");
            EmitSMul16x8Shr8_HL("__sdot2_x");
        }
        // Preserve the scaled result while evaluating the zero-product input.
        EmitAsm("PUSH_HL");
        CompileDiscard(args[1]);
        EmitAsm("POP_HL");
        return;
    }

    // x*ax
    if (!TryEmitDot2Pow2Term(args[0], args[2], signed: true, q1_7: false, out _))
    {
        CompileIntoHL(args[0]);
        EmitAsm("PUSH_HL");
        CompileIntoA(args[2]);
        EmitAsm("LD_C_A");
        EmitAsm("POP_HL");
        EmitSMul16x8Shr8_HL("__sdot2_x");
    }
    EmitAsm("PUSH_HL");

    // y*ay
    if (!TryEmitDot2Pow2Term(args[1], args[3], signed: true, q1_7: false, out _))
    {
        CompileIntoHL(args[1]);
        EmitAsm("PUSH_HL");
        CompileIntoA(args[3]);
        EmitAsm("LD_C_A");
        EmitAsm("POP_HL");
        EmitSMul16x8Shr8_HL("__sdot2_y");
    }
    EmitAsm("POP_DE");
    EmitAsm("ADD_HL_DE");
    return;
}

Compute a signed three-term dot product.

Syntax

u16 __sdot3_q1_7(u16 a0, u16 a1, u16 a2, u8 b0, u8 b1, u8 b2);

Parameters

a0

Signed 16-bit bit pattern, representing −32768..32767.

a1

Signed 16-bit bit pattern, representing −32768..32767.

a2

Signed 16-bit bit pattern, representing −32768..32767.

b0

Signed byte bit pattern, coefficient −128..127.

b1

Signed byte bit pattern, coefficient −128..127.

b2

Signed byte bit pattern, coefficient −128..127.

Return value

Each term is 2*trunc(a*b/256). Sum the terms; returns the low 16 bits.

Conditions and limits

GB products are divided by 256; signed results truncate toward zero. Q1.7 variants double that truncated result and can differ by one from exact division by 128. Terms are rounded separately; final addition wraps at 16 bits.

Usage example

// Compare literal coefficients with values read from RAM.
result[16]=__sdot3_q1_7(-513,769,-1025,-64,127,-3);
v0=-513;v1=769;v2=-1025;v3=-64;v4=127;v5=-3;
result[17]=__sdot3_q1_7(v0,v1,v2,v3,v4,v5);
// Reverse coefficient signs and verify negative products.
result[18]=__sdot3_q1_7(-513,769,-1025,64,-127,3);
v0=-513;v1=769;v2=-1025;v3=64;v4=-127;v5=3;
result[19]=__sdot3_q1_7(v0,v1,v2,v3,v4,v5);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Compare literal inputs with values stored in RAM. Representative results appear as unsigned 16-bit values; negatives use two’s-complement bit patterns. GB rescales fixed-point products, while FC returns integer products, so identical inputs need not give identical results.

The excerpt stores these 16-bit values: result[16]=1042, result[17]=1042, result[18]=64494, result[19]=64494. Each literal-input calculation matches its RAM-input counterpart. The screen shows representative values; the result array holds every result.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch3_math.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch3_math.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --ramsize=none

if (funcName == "__sdot3_q1_7")
            {
                if (args.Length != 6) Error(expr, "__sdot3_q1_7 requires 6 arguments");
                LastCallReturnsHL = true;

                // x*ax
                EmitDotTermToHL(args[0], args[3], signed: true, q1_7: true, labelPrefix: "__sdot3_q1_7_x");
                EmitAsm("PUSH_HL");

                // y*ay
                EmitDotTermToHL(args[1], args[4], signed: true, q1_7: true, labelPrefix: "__sdot3_q1_7_y");
                EmitAsm("POP_DE");
                EmitAsm("ADD_HL_DE");
                EmitAsm("PUSH_HL");

                // z*az
                EmitDotTermToHL(args[2], args[5], signed: true, q1_7: true, labelPrefix: "__sdot3_q1_7_z");
                EmitAsm("POP_DE");
                EmitAsm("ADD_HL_DE");
                return;
            }

Compute a signed three-term dot product.

Syntax

u16 __sdot3_q8_8(u16 a0, u16 a1, u16 a2, u8 b0, u8 b1, u8 b2);

Parameters

a0

Signed 16-bit bit pattern, representing −32768..32767.

a1

Signed 16-bit bit pattern, representing −32768..32767.

a2

Signed 16-bit bit pattern, representing −32768..32767.

b0

Signed byte bit pattern, coefficient −128..127.

b1

Signed byte bit pattern, coefficient −128..127.

b2

Signed byte bit pattern, coefficient −128..127.

Return value

Each term is trunc(a*b/256). Sum the terms; returns the low 16 bits.

Conditions and limits

GB products are divided by 256; signed results truncate toward zero. Q1.7 variants double that truncated result and can differ by one from exact division by 128. Terms are rounded separately; final addition wraps at 16 bits.

Usage example

// Compare literal coefficients with values read from RAM.
result[8]=__sdot3_q8_8(-513,769,-1025,-64,127,-3);
v0=-513;v1=769;v2=-1025;v3=-64;v4=127;v5=-3;
result[9]=__sdot3_q8_8(v0,v1,v2,v3,v4,v5);
// Reverse coefficient signs and verify negative products.
result[10]=__sdot3_q8_8(-513,769,-1025,64,-127,3);
v0=-513;v1=769;v2=-1025;v3=64;v4=-127;v5=3;
result[11]=__sdot3_q8_8(v0,v1,v2,v3,v4,v5);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Compare literal inputs with values stored in RAM. Representative results appear as unsigned 16-bit values; negatives use two’s-complement bit patterns. GB rescales fixed-point products, while FC returns integer products, so identical inputs need not give identical results.

The excerpt stores these 16-bit values: result[8]=521, result[9]=521, result[10]=65015, result[11]=65015. Each literal-input calculation matches its RAM-input counterpart. The screen shows representative values; the result array holds every result.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch3_math.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch3_math.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --ramsize=none

if (funcName == "__sdot3_q8_8")
            {
                if (args.Length != 6) Error(expr, "__sdot3_q8_8 requires 6 arguments");
                LastCallReturnsHL = true;

                // x*ax
                EmitDotTermToHL(args[0], args[3], signed: true, q1_7: false, labelPrefix: "__sdot3_x");
                EmitAsm("PUSH_HL");

                // y*ay
                EmitDotTermToHL(args[1], args[4], signed: true, q1_7: false, labelPrefix: "__sdot3_y");
                EmitAsm("POP_DE");
                EmitAsm("ADD_HL_DE");
                EmitAsm("PUSH_HL");

                // z*az
                EmitDotTermToHL(args[2], args[5], signed: true, q1_7: false, labelPrefix: "__sdot3_z");
                EmitAsm("POP_DE");
                EmitAsm("ADD_HL_DE");
                return;
            }

Write one tile-number byte to the tile map; this selects an existing tile image, not new pixel data.

The destination is always 0x9800 + 32*y + x, regardless of which maps LCDC selects for the background and window.

Does not wait for VRAM access. Call only while the LCD is off or within a caller-managed writable interval with enough time for the whole transfer.

Syntax

__settile_fast(x, y, tile);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

x, y

Coordinates in 8×8 tiles, each from 0 to 31. Keep the complete write inside the 32×32 map; coordinates are not clipped.

tile

Tile number, 0–255. LCDC bit 4 determines how the number addresses tile-image data. It is not a VRAM byte address.

Return value

None (void).

Conditions and limits

Tile bytes go to the currently selected VRAM bank. On CGB, select bank 0 for tile numbers; this call does not switch banks for you.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settile_fast
// Write one tile-number byte to the tile map; this selects an existing tile image, not
// new pixel data. The destination is always `0x9800 + 32*y + x`, regardless of which
// maps LCDC selects for the background and window.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_color_example.h"
void __settile_fast(u8 x, u8 y, u8 tile);

void main() {
    u8 failures;
    failures = 0;
    tile_color_example_begin();
    __settile_fast(2, 3, 'A');
    if (tile_example_read(0x9862, 0) != 'A') { failures++; }
    if (tile_example_read(0x9C62, 0) != 0) { failures++; }
    tile_example_finish(failures, 0);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

On CGB, the sample characters and status text are blue on white. The setup gives palette 0 a blue ink color; it does not change the tile-map attributes. On DMG, the same characters are black on white.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=3), or pixel coordinates (16,24). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

A

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settile_fast.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settile_fast.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

{
                if (args.Length != 3) Error(expr, "__settile_unsafe requires 3 arguments");

                // Evaluate args left-to-right (matches normal call semantics)
                // Preserve x,y while evaluating tile.
                CompileIntoA(args[0]);
                EmitAsm("LD_L_A");
                EmitAsm("LD_H_IMM", new AsmOperand(0, AddressMode.Immediate));
                EmitAsm("PUSH_HL"); // x

                CompileIntoA(args[1]);
                EmitAsm("LD_L_A");
                EmitAsm("LD_H_IMM", new AsmOperand(0, AddressMode.Immediate));
                EmitAsm("PUSH_HL"); // y

                CompileIntoA(args[2]);
                EmitAsm("LD_C_A"); // tile

                // Restore y -> A, x -> B
                EmitAsm("POP_HL");
                EmitAsm("LD_A_L");
                EmitAsm("LD_D_A"); // y temp

                EmitAsm("POP_HL");
                EmitAsm("LD_A_L");
                EmitAsm("LD_B_A"); // x

                EmitAsm("LD_A_D"); // y

                UsedSetTileFastCore = true;
                EmitAsm("CALL", new AsmOperand("__settile_fast_core", AddressMode.Absolute));
                return;
            }

            // 2.6b __settile_bulk(dest_u16, src_u16, count_u8)
            // v9: bulk tile-map copy (LCD ON safe with wait+DI/EI inside core).
            if (funcName == "__settile_bulk")
            {
                if (args.Length != 3) Error(expr, "__settile_bulk requires 3 arguments");

                Expr bulkCountExpr = FoldConstants(args[2]);

                // dest

Write a 16×16-pixel cell into a RAM tile-map buffer: the four 8×8 tile numbers are tile,tile+1 on top and tile+2,tile+3 below. Values wrap at 256. This does not transfer anything to VRAM.

Syntax

__settilebg16_buf(buf, x, y, tile);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

buf

A RAM buffer with 32 bytes per tile row. A full 32×32 map needs 1024 bytes. The upper-left byte is at 64*y + 2*x; the four offsets are 0,1,32,33 from there.

x, y

Coordinates in 16×16-pixel cells, each from 0 to 15 for a full 32×32-tile buffer. These differ from the 8×8-tile coordinates used by scalar setters.

tile

Tile number, 0–255. LCDC bit 4 determines how the number addresses tile-image data. It is not a VRAM byte address.

Return value

None (void).

Conditions and limits

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilebg16_buf
// Write a 16×16-pixel cell into a RAM tile-map buffer: the four 8×8 tile numbers are
// `tile,tile+1` on top and `tile+2,tile+3` below. Values wrap at 256. This does not
// transfer anything to VRAM.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_color_example.h"
u8 example_tiles[1024];
u8 example_attrs[1024];
void __memset(void* dest, u8 value, u16 len);
void __settilebg16_buf(u8* buf, u8 x, u8 y, u8 tile);
void __settilebg16cgb_buf(u8* tilebuf, u8* attrbuf, u8 x, u8 y, u8 tile, u8 attr);
void __settilebg16_flush(const u8* buf, u8 y, u8 x, u8 count);
void __settilebg16cgb_flush(const u8* tilebuf, const u8* attrbuf, u8 y, u8 x, u8 count);

void main() {
    u8 failures;
    failures = 0;
    tile_color_example_begin();
    __memset(example_tiles, 0, 1024);
    __memset(example_attrs, 0, 1024);
    __settilebg16_buf(example_tiles, 1, 1, 'A');
    // The buffer operation must not write to VRAM yet.
    if (tile_example_read(0x9C42, 0) != 0) { failures++; }
    // Transfer the prepared cell so its four characters can be seen.
    __settilebg16_flush(example_tiles, 1, 2, 2);
    if (tile_example_read(0x9C42, 0) != 'A') { failures++; }
    if (tile_example_read(0x9C43, 0) != 'B') { failures++; }
    if (tile_example_read(0x9C62, 0) != 'C') { failures++; }
    if (tile_example_read(0x9C63, 0) != 'D') { failures++; }
    if (example_tiles[66] != 'A') { failures++; }
    if (example_tiles[99] != 'D') { failures++; }
    if (tile_example_read(0x9C44, 0) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

The visible cell contains AB above CD, at tile coordinates (2,2). This is one 16×16-pixel cell at cell coordinates (1,1). Buffer examples first verify that RAM preparation leaves VRAM unchanged, then flush the cell; flush examples prepare the RAM bytes explicitly before transferring them.

On CGB, the sample characters and status text are blue on white. The setup gives palette 0 a blue ink color; it does not change the tile-map attributes. On DMG, the same characters are black on white.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=2), or pixel coordinates (16,16). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

AB
CD

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilebg16_buf.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilebg16_buf.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

{
                if (args.Length != 4) Error(expr, "__settilebg16_buf requires 4 arguments");
                EmitTile16BufferedWriteIntrinsic(args[0], args[1], args[2], args[3], incrementQuad: true, labelPrefix: "settilebg16buf");
                return;
            }

            // Update tile and attribute RAM buffers separately, repeating the attribute across the cell.
            if (funcName == "__settilebg16cgb_buf")
            {
                if (args.Length != 6) Error(expr, "__settilebg16cgb_buf requires 6 arguments");
                EmitTile16BufferedWriteIntrinsic(args[0], args[2], args[3], args[4], incrementQuad: true, labelPrefix: "settilebg16cgbbuf_tile");
                EmitTile16BufferedWriteIntrinsic(args[1], args[2], args[3], args[5], incrementQuad: false, labelPrefix: "settilebg16cgbbuf_attr");
                return;
            }

            // Flush both tile rows belonging to the requested buffered cell row.
            if (funcName == "__settilebg16_flush")
            {
                if (args.Length != 4) Error(expr, "__settilebg16_flush requires 4 arguments");
                EmitTile16FlushRowsIntrinsic(args[0], args[1], args[2], args[3], cgbAttr: false, labelPrefix: "settilebg16flush");
                return;
            }

            // Flush the tile buffer first and copy attributes only when CGB hardware is available.
            if (funcName == "__settilebg16cgb_flush")
            {
                if (args.Length != 5) Error(expr, "__settilebg16cgb_flush requires 5 arguments");
                EmitTile16FlushRowsIn

Transfer two adjacent tile rows from the RAM buffer to the LCDC-selected BG map. The source offset is 64*y + x; count bytes are copied from that row and from the row 32 bytes below it.

Waits for writable VRAM when necessary. The LCD-on path uses interrupt masking and can enable interrupts afterward; it is not a promise to preserve the caller's interrupt state or to finish within one VBlank.

Syntax

__settilebg16_flush(buf, y, x, count);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

buf

Readable tile-map buffer with a 32-byte row stride. A full map occupies 1024 bytes. The two-buffer form takes separate tile-number and attribute arrays with the same layout; it does not interleave them.

y, x, count

Argument order is y,x,count. y is a 16-pixel cell row (0–15); x and count are 8-pixel tile units. Keep x+count <= 32. For one cell at (2,3), use y=3,x=4,count=2.

Return value

None (void).

Conditions and limits

Tile bytes go to the currently selected VRAM bank. On CGB, select bank 0 for tile numbers; this call does not switch banks for you.

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilebg16_flush
// Transfer two adjacent tile rows from the RAM buffer to the LCDC-selected BG map. The
// source offset is `64*y + x`; `count` bytes are copied from that row and from the row
// 32 bytes below it. Waits for writable VRAM when necessary. The LCD-on path uses
// interrupt masking and can enable interrupts afterward; it is not a promise to preserve
// the caller's interrupt state or to finish within one VBlank.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_color_example.h"
u8 example_tiles[1024];
u8 example_attrs[1024];
void __memset(void* dest, u8 value, u16 len);
void __settilebg16_buf(u8* buf, u8 x, u8 y, u8 tile);
void __settilebg16cgb_buf(u8* tilebuf, u8* attrbuf, u8 x, u8 y, u8 tile, u8 attr);
void __settilebg16_flush(const u8* buf, u8 y, u8 x, u8 count);
void __settilebg16cgb_flush(const u8* tilebuf, const u8* attrbuf, u8 y, u8 x, u8 count);

void main() {
    u8 failures;
    failures = 0;
    tile_color_example_begin();
    __memset(example_tiles, 0, 1024);
    __memset(example_attrs, 0, 1024);
    example_tiles[66]='A'; example_tiles[67]='B';
    example_tiles[98]='C'; example_tiles[99]='D';
    __settilebg16_flush(example_tiles, 1, 2, 2);
    if (tile_example_read(0x9C42, 0) != 'A') { failures++; }
    if (tile_example_read(0x9C43, 0) != 'B') { failures++; }
    if (tile_example_read(0x9C62, 0) != 'C') { failures++; }
    if (tile_example_read(0x9C63, 0) != 'D') { failures++; }
    if (example_tiles[66] != 'A') { failures++; }
    if (example_tiles[99] != 'D') { failures++; }
    if (tile_example_read(0x9C44, 0) != 0) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

The visible cell contains AB above CD, at tile coordinates (2,2). This is one 16×16-pixel cell at cell coordinates (1,1). Buffer examples first verify that RAM preparation leaves VRAM unchanged, then flush the cell; flush examples prepare the RAM bytes explicitly before transferring them.

On CGB, the sample characters and status text are blue on white. The setup gives palette 0 a blue ink color; it does not change the tile-map attributes. On DMG, the same characters are black on white.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=2), or pixel coordinates (16,16). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

AB
CD

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilebg16_flush.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilebg16_flush.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

{
                if (args.Length != 4) Error(expr, "__settilebg16_flush requires 4 arguments");
                EmitTile16FlushRowsIntrinsic(args[0], args[1], args[2], args[3], cgbAttr: false, labelPrefix: "settilebg16flush");
                return;
            }

            // Flush the tile buffer first and copy attributes only when CGB hardware is available.
            if (funcName == "__settilebg16cgb_flush")
            {
                if (args.Length != 5) Error(expr, "__settilebg16cgb_flush requires 5 arguments");
                EmitTile16FlushRowsIntrinsic(args[0], args[2], args[3], args[4], cgbAttr: false, labelPrefix: "settilebg16cgbflush_tile");
                if (IsKnownCgbRuntimeTrue())
                {
                    EmitSetVbkUnchecked(1);
                    EmitTile16FlushRowsIntrinsic(args[1], args[2], args[3], args[4], cgbAttr: true, labelPrefix: "settilebg16cgbflush_attr");
                }
                else
                {
                    AsmOperand skip = MakeUniqueLabel("settilebg16cgbflush_skip");
                    AsmOperand done = MakeUniqueLabel("settilebg16cgbflush_done");
                    EmitRuntimeCgbCheckCall();
                    EmitAsm("OR_A");
                    // Two unrolled row copies can exceed the relative-branch range.
                    EmitAsm("JP_Z", skip);
                    EmitSetVbkUnchecked(1);
                    EmitTile16FlushRowsIntrinsic(args[1], args[2], args[3], args[4], cgbAttr: true, labelPrefix: "settilebg16cgbflush_attr");
                    EmitAsm("JR", done);

Write a 16×16-pixel cell into a RAM tile-map buffer: the four 8×8 tile numbers are tile,tile+1 on top and tile+2,tile+3 below. Values wrap at 256. This does not transfer anything to VRAM.

Also write the same attr byte to all four corresponding cells in the separate attribute buffer. Both buffers are ordinary RAM, so this preparation also runs on DMG.

Syntax

__settilebg16cgb_buf(tilebuf, attrbuf, x, y, tile, attr);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

tilebuf, attrbuf

A RAM buffer with 32 bytes per tile row. A full 32×32 map needs 1024 bytes. The upper-left byte is at 64*y + 2*x; the four offsets are 0,1,32,33 from there.

x, y

Coordinates in 16×16-pixel cells, each from 0 to 15 for a full 32×32-tile buffer. These differ from the 8×8-tile coordinates used by scalar setters.

tile

Tile number, 0–255. LCDC bit 4 determines how the number addresses tile-image data. It is not a VRAM byte address.

attr

CGB attribute byte: bits 0–2 select palette 0–7; bit 3 selects tile-data bank; bits 5 and 6 flip horizontally and vertically; bit 7 sets BG/window priority. Keep unused bit 4 zero.

Return value

None (void).

Conditions and limits

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilebg16cgb_buf
// Write a 16×16-pixel cell into a RAM tile-map buffer: the four 8×8 tile numbers are
// `tile,tile+1` on top and `tile+2,tile+3` below. Values wrap at 256. This does not
// transfer anything to VRAM. Also write the same `attr` byte to all four corresponding
// cells in the separate attribute buffer. Both buffers are ordinary RAM, so this
// preparation also runs on DMG.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"
u8 example_tiles[1024];
u8 example_attrs[1024];
void __memset(void* dest, u8 value, u16 len);
void __settilebg16_buf(u8* buf, u8 x, u8 y, u8 tile);
void __settilebg16cgb_buf(u8* tilebuf, u8* attrbuf, u8 x, u8 y, u8 tile, u8 attr);
void __settilebg16_flush(const u8* buf, u8 y, u8 x, u8 count);
void __settilebg16cgb_flush(const u8* tilebuf, const u8* attrbuf, u8 y, u8 x, u8 count);

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __memset(example_tiles, 0, 1024);
    __memset(example_attrs, 0, 1024);
    __settilebg16cgb_buf(example_tiles, example_attrs, 1, 1, 'A', 2);
    // The buffer operation must not write to VRAM yet.
    if (tile_example_read(0x9C42, 0) != 0) { failures++; }
    // Transfer the prepared cell so its four characters can be seen.
    __settilebg16cgb_flush(example_tiles, example_attrs, 1, 2, 2);
    if (tile_example_read(0x9C42, 0) != 'A') { failures++; }
    if (tile_example_read(0x9C43, 0) != 'B') { failures++; }
    if (tile_example_read(0x9C62, 0) != 'C') { failures++; }
    if (tile_example_read(0x9C63, 0) != 'D') { failures++; }
    if (example_tiles[66] != 'A') { failures++; }
    if (example_tiles[99] != 'D') { failures++; }
    if (tile_example_read(0x9C44, 0) != 0) { failures++; }
    if (example_attrs[66] != 2) { failures++; }
    if (example_attrs[99] != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C42, 1) != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C63, 1) != 2) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

The visible cell contains AB above CD, at tile coordinates (2,2). This is one 16×16-pixel cell at cell coordinates (1,1). Buffer examples first verify that RAM preparation leaves VRAM unchanged, then flush the cell; flush examples prepare the RAM bytes explicitly before transferring them.

All four characters are blue on CGB because the four attribute bytes are 2. They are black on DMG.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=2), or pixel coordinates (16,16). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

AB
CD

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilebg16cgb_buf.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilebg16cgb_buf.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

{
                if (args.Length != 6) Error(expr, "__settilebg16cgb_buf requires 6 arguments");
                EmitTile16BufferedWriteIntrinsic(args[0], args[2], args[3], args[4], incrementQuad: true, labelPrefix: "settilebg16cgbbuf_tile");
                EmitTile16BufferedWriteIntrinsic(args[1], args[2], args[3], args[5], incrementQuad: false, labelPrefix: "settilebg16cgbbuf_attr");
                return;
            }

            // Flush both tile rows belonging to the requested buffered cell row.
            if (funcName == "__settilebg16_flush")
            {
                if (args.Length != 4) Error(expr, "__settilebg16_flush requires 4 arguments");
                EmitTile16FlushRowsIntrinsic(args[0], args[1], args[2], args[3], cgbAttr: false, labelPrefix: "settilebg16flush");
                return;
            }

            // Flush the tile buffer first and copy attributes only when CGB hardware is available.
            if (funcName == "__settilebg16cgb_flush")
            {
                if (args.Length != 5) Error(expr, "__settilebg16cgb_flush requires 5 arguments");
                EmitTile16FlushRowsIntrinsic(args[0], args[2], args[3], args[4], cgbAttr: false, labelPrefix: "settilebg16cgbflush_tile");
                if (IsKnownCgbRuntimeTrue())
                {
                    EmitSetVbkUnchecked(1);
                    EmitTile16FlushRowsIntrinsic(args[1], args[2], args[3], args[4], cgbAttr: true, labelPrefix: "settilebg16cgbflush_attr");
                }
                else
                {
                    AsmOperand ski

Transfer two adjacent tile rows from the RAM buffer to the LCDC-selected BG map. The source offset is 64*y + x; count bytes are copied from that row and from the row 32 bytes below it.

Write a tile number and its CGB attribute. On DMG, only the tile-number write is performed. On CGB, enter with VRAM bank 0 selected; attributes use bank 1 and the call finishes with VBK=0.

Waits for writable VRAM when necessary. The LCD-on path uses interrupt masking and can enable interrupts afterward; it is not a promise to preserve the caller's interrupt state or to finish within one VBlank.

Syntax

__settilebg16cgb_flush(tilebuf, attrbuf, y, x, count);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

tilebuf, attrbuf

Readable tile-map buffer with a 32-byte row stride. A full map occupies 1024 bytes. The two-buffer form takes separate tile-number and attribute arrays with the same layout; it does not interleave them.

y, x, count

Argument order is y,x,count. y is a 16-pixel cell row (0–15); x and count are 8-pixel tile units. Keep x+count <= 32. For one cell at (2,3), use y=3,x=4,count=2.

Return value

None (void).

Conditions and limits

The example uses gb_common.h: m_init() loads the supplied ASCII font with character codes as tile numbers. m_wait(); M_LCDC=0; stops the LCD during VBlank before unsafe transfers. The final LCDC value selects which map is visible.

Usage example

// __settilebg16cgb_flush
// Transfer two adjacent tile rows from the RAM buffer to the LCDC-selected BG map. The
// source offset is `64*y + x`; `count` bytes are copied from that row and from the row
// 32 bytes below it. Write a tile number and its CGB attribute. On DMG, only the tile-
// number write is performed. On CGB, enter with VRAM bank 0 selected; attributes use
// bank 1 and the call finishes with `VBK=0`.
// Expected: FAILED CHECKS 000, with the written tile data in the selected map.
#include "gb_tile_example.h"
u8 example_tiles[1024];
u8 example_attrs[1024];
void __memset(void* dest, u8 value, u16 len);
void __settilebg16_buf(u8* buf, u8 x, u8 y, u8 tile);
void __settilebg16cgb_buf(u8* tilebuf, u8* attrbuf, u8 x, u8 y, u8 tile, u8 attr);
void __settilebg16_flush(const u8* buf, u8 y, u8 x, u8 count);
void __settilebg16cgb_flush(const u8* tilebuf, const u8* attrbuf, u8 y, u8 x, u8 count);

void main() {
    u8 failures;
    failures = 0;
    tile_example_begin();
    __memset(example_tiles, 0, 1024);
    __memset(example_attrs, 0, 1024);
    example_tiles[66]='A'; example_tiles[67]='B';
    example_tiles[98]='C'; example_tiles[99]='D';
    example_attrs[66]=2; example_attrs[67]=2;
    example_attrs[98]=2; example_attrs[99]=2;
    __settilebg16cgb_flush(example_tiles, example_attrs, 1, 2, 2);
    if (tile_example_read(0x9C42, 0) != 'A') { failures++; }
    if (tile_example_read(0x9C43, 0) != 'B') { failures++; }
    if (tile_example_read(0x9C62, 0) != 'C') { failures++; }
    if (tile_example_read(0x9C63, 0) != 'D') { failures++; }
    if (example_tiles[66] != 'A') { failures++; }
    if (example_tiles[99] != 'D') { failures++; }
    if (tile_example_read(0x9C44, 0) != 0) { failures++; }
    if (example_attrs[66] != 2) { failures++; }
    if (example_attrs[99] != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C42, 1) != 2) { failures++; }
    if (__cgb_is_cgb() && tile_example_read(0x9C63, 1) != 2) { failures++; }
    tile_example_finish(failures, 1);
}

Expected result

The selected map shows the written characters or filled area. The program reads back the addressed tile bytes and, on CGB, the attribute bytes; FAILED CHECKS 000 means those comparisons passed. Both maps initially contain zero, and the example selects 0x9C00 for BG/window before the demonstrated call, so a fixed-map call can be distinguished from a selected-map call. These examples perform the writes with the LCD off; they do not measure LCD-on timing.

The visible cell contains AB above CD, at tile coordinates (2,2). This is one 16×16-pixel cell at cell coordinates (1,1). Buffer examples first verify that RAM preparation leaves VRAM unchanged, then flush the cell; flush examples prepare the RAM bytes explicitly before transferring them.

All four characters are blue on CGB because the four attribute bytes are 2. They are black on DMG.

Expected image: the following tile pattern starts at tile coordinates (x=2, y=2), or pixel coordinates (16,16). Each character occupies one 8×8 tile. Read the pattern from top to bottom and left to right; the surrounding tiles remain blank.

AB
CD

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\__settilebg16cgb_flush.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\__settilebg16cgb_flush.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-disasm

{
                if (args.Length != 5) Error(expr, "__settilebg16cgb_flush requires 5 arguments");
                EmitTile16FlushRowsIntrinsic(args[0], args[2], args[3], args[4], cgbAttr: false, labelPrefix: "settilebg16cgbflush_tile");
                if (IsKnownCgbRuntimeTrue())
                {
                    EmitSetVbkUnchecked(1);
                    EmitTile16FlushRowsIntrinsic(args[1], args[2], args[3], args[4], cgbAttr: true, labelPrefix: "settilebg16cgbflush_attr");
                }
                else
                {
                    AsmOperand skip = MakeUniqueLabel("settilebg16cgbflush_skip");
                    AsmOperand done = MakeUniqueLabel("settilebg16cgbflush_done");
                    EmitRuntimeCgbCheckCall();
                    EmitAsm("OR_A");
                    // Two unrolled row copies can exceed the relative-branch range.
                    EmitAsm("JP_Z", skip);
                    EmitSetVbkUnchecked(1);
                    EmitTile16FlushRowsIntrinsic(args[1], args[2], args[3], args[4], cgbAttr: true, labelPrefix: "settilebg16cgbflush_attr");
                    EmitAsm("JR", done);
                    EmitLabel(skip);
                    EmitLabel(done);
                }
                return;
            }

            // 2.14 __getbgmapbase() -> u16 in HL
// Returns the BG tilemap base address selected by LCDC bit3:
// bit3=0 => 0x9800, bit3=1 => 0x9C00
// Treated as a compiler intrinsic (no C definition required).
if (funcName == "__getbgmapbase")
{
    if (args.Length != 0) Error(expr, "__getb

Compute a signed multiply-accumulate.

Syntax

u16 __smac16(u16 acc, u16 a, u8 b);

Parameters

acc

16-bit accumulator to add.

a

Signed 16-bit bit pattern, representing −32768..32767.

b

Signed byte bit pattern, coefficient −128..127.

Return value

Each term is trunc(a*b/256), added to acc; returns the low 16 bits.

Conditions and limits

GB products are divided by 256; signed results truncate toward zero. Q1.7 variants double that truncated result and can differ by one from exact division by 128. Terms are rounded separately; final addition wraps at 16 bits.

Usage example

// Compare literal coefficients with values read from RAM.
result[26]=__smac16(65500,-513,-64);
v0=65500;v1=-513;v2=-64;
result[27]=__smac16(v0,v1,v2);
// Reverse coefficient signs and verify negative products.
result[28]=__smac16(65500,-513,64);
v0=65500;v1=-513;v2=64;
result[29]=__smac16(v0,v1,v2);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Compare literal inputs with values stored in RAM. Representative results appear as unsigned 16-bit values; negatives use two’s-complement bit patterns. GB rescales fixed-point products, while FC returns integer products, so identical inputs need not give identical results.

The excerpt stores these 16-bit values: result[26]=92, result[27]=92, result[28]=65372, result[29]=65372. Each literal-input calculation matches its RAM-input counterpart. The screen shows representative values; the result array holds every result.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch3_math.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch3_math.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --ramsize=none

if (funcName == "__smac16")
            {
                if (args.Length != 3) Error(expr, "__smac16 requires 3 arguments");

                // mul = (a*b)>>8 (signed)
                EmitDotTermToHL(args[1], args[2], signed: true, q1_7: false, labelPrefix: "__smac16_mul");

                // acc + mul
                EmitAsm("PUSH_HL");
                CompileIntoHL(args[0]);
                EmitAsm("POP_DE");
                EmitAsm("ADD_HL_DE");
                LastCallReturnsHL = true;
                return;
            }

Compute a signed multiply-accumulate.

Syntax

u16 __smac16_q1_7(u16 acc, u16 a, u8 b);

Parameters

acc

16-bit accumulator to add.

a

Signed 16-bit bit pattern, representing −32768..32767.

b

Signed byte bit pattern, coefficient −128..127.

Return value

Each term is 2*trunc(a*b/256), added to acc; returns the low 16 bits.

Conditions and limits

GB products are divided by 256; signed results truncate toward zero. Q1.7 variants double that truncated result and can differ by one from exact division by 128. Terms are rounded separately; final addition wraps at 16 bits.

Usage example

// Compare literal coefficients with values read from RAM.
result[0]=__smac16_q1_7(65500,-513,-64);
v0=65500;v1=-513;v2=-64;
result[1]=__smac16_q1_7(v0,v1,v2);
// Reverse coefficient signs and verify negative products.
result[2]=__smac16_q1_7(65500,-513,64);
v0=65500;v1=-513;v2=64;
result[3]=__smac16_q1_7(v0,v1,v2);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Compare literal inputs with values stored in RAM. Representative results appear as unsigned 16-bit values; negatives use two’s-complement bit patterns. GB rescales fixed-point products, while FC returns integer products, so identical inputs need not give identical results.

The excerpt stores these 16-bit values: result[0]=220, result[1]=220, result[2]=65244, result[3]=65244. Each literal-input calculation matches its RAM-input counterpart. The screen shows representative values; the result array holds every result.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch3_math.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch3_math.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --ramsize=none

if (funcName == "__smac16_q1_7")
            {
                if (args.Length != 3) Error(expr, "__smac16_q1_7 requires 3 arguments");

                // mul = (a*b)>>7 (approx via >>8 then *2)
                EmitDotTermToHL(args[1], args[2], signed: true, q1_7: true, labelPrefix: "__smac16_q1_7_mul");

                // acc + mul
                EmitAsm("PUSH_HL");
                CompileIntoHL(args[0]);
                EmitAsm("POP_DE");
                EmitAsm("ADD_HL_DE");
                LastCallReturnsHL = true;
                return;
            }

Compute a signed multiplication.

Syntax

u16 __smul16x8_q1_7(u16 a, u8 b);

Parameters

a

Signed 16-bit bit pattern, representing −32768..32767.

b

Signed byte bit pattern, coefficient −128..127.

Return value

Each term is 2*trunc(a*b/256); returns the low 16 bits.

Conditions and limits

GB products are divided by 256; signed results truncate toward zero. Q1.7 variants double that truncated result and can differ by one from exact division by 128. Terms are rounded separately; final addition wraps at 16 bits.

Usage example

// Compare literal coefficients with values read from RAM.
result[12]=__smul16x8_q1_7(-513,-64);
v0=-513;v1=-64;
result[13]=__smul16x8_q1_7(v0,v1);
// Reverse coefficient signs and verify negative products.
result[14]=__smul16x8_q1_7(-513,64);
v0=-513;v1=64;
result[15]=__smul16x8_q1_7(v0,v1);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Compare literal inputs with values stored in RAM. Representative results appear as unsigned 16-bit values; negatives use two’s-complement bit patterns. GB rescales fixed-point products, while FC returns integer products, so identical inputs need not give identical results.

The excerpt stores these 16-bit values: result[12]=256, result[13]=256, result[14]=65280, result[15]=65280. Each literal-input calculation matches its RAM-input counterpart. The screen shows representative values; the result array holds every result.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch3_math.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch3_math.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --ramsize=none

if (funcName == "__smul16x8_q1_7")
            {
                if (args.Length != 2) Error(expr, "__smul16x8_q1_7 requires 2 arguments");

                EmitDotTermToHL(args[0], args[1], signed: true, q1_7: true, labelPrefix: "__smul16x8_q1_7");
                LastCallReturnsHL = true;
                return;
            }

Read one SRAM byte at a CPU address.

Syntax

u8 __sram_read8(u16 address);

Parameters

address

CPU address in $A000..$BFFF.

Return value

Returns the byte without checking RAM presence or data validity.

Conditions and limits

Writes 0x0A to $0000 to enable RAM before access, then writes zero to disable it afterward. Does not select the bank or validate the address; the caller configures the RAM bank. No save header or checksum is managed.

Usage example

*((u8*)0x4000)=0;result[12]=__sram_read8(0xA006);result[19]=*((u8*)0xA006);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Save three bytes, 7/42/255, then test length mismatch, an invalid slot and a damaged checksum. A successful load yields middle byte 42; a failed read preserves destination 77; validation after clearing returns 0.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch3_save.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch3_save.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --ramsize=8k

if (funcName == "__sram_read8")
            {
                if (args.Length != 1) Error(expr, "__sram_read8(addr) expects 1 argument");

                CompileIntoHL(args[0]);
                EmitAsm("PUSH_HL");

                EmitAsm("LD_A_IMM", new AsmOperand(0x0A, AddressMode.Immediate));
                EmitAsm("LD_MEM_A", new AsmOperand(0x0000, AddressMode.Absolute));

                EmitAsm("POP_HL");
                EmitAsm("LD_A_HL");
                EmitAsm("LD_B_A");

                EmitAsm("LD_A_IMM", new AsmOperand(0x00, AddressMode.Immediate));
                EmitAsm("LD_MEM_A", new AsmOperand(0x0000, AddressMode.Absolute));
                EmitAsm("LD_A_B");
                return;
            }

Write one SRAM byte at a CPU address.

Syntax

void __sram_write8(u16 address, u8 value);

Parameters

address

CPU address in $A000..$BFFF.

value

Byte value 0..255.

Return value

No return value.

Conditions and limits

Writes 0x0A to $0000 to enable RAM before access, then writes zero to disable it afterward. Does not select the bank or validate the address; the caller configures the RAM bank. No save header or checksum is managed.

Usage example

__sram_write8(0xA006,8);result[20]=*((u8*)0xA006);result[13]=save_exists(0);readback[0]=77;result[14]=save_read(0,readback,3);result[15]=readback[0];

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Save three bytes, 7/42/255, then test length mismatch, an invalid slot and a damaged checksum. A successful load yields middle byte 42; a failed read preserves destination 77; validation after clearing returns 0.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch3_save.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch3_save.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --ramsize=8k

if (funcName == "__sram_write8")
            {
                if (args.Length != 2) Error(expr, "__sram_write8(addr, value) expects 2 arguments");

                CompileIntoHL(args[0]);
                EmitAsm("PUSH_HL");
                CompileIntoA(args[1]);
                EmitAsm("LD_C_A");

                EmitAsm("LD_A_IMM", new AsmOperand(0x0A, AddressMode.Immediate));
                EmitAsm("LD_MEM_A", new AsmOperand(0x0000, AddressMode.Absolute));

                EmitAsm("POP_HL");
                EmitAsm("LD_A_C");
                EmitAsm("LD_HL_A");

                EmitAsm("LD_A_IMM", new AsmOperand(0x00, AddressMode.Immediate));
                EmitAsm("LD_MEM_A", new AsmOperand(0x0000, AddressMode.Absolute));
                return;
            }

Read the effective WRAM bank mapped at $D000–$DFFF. The compiler reads SVBK bits 0–2 and converts raw selector 0 to bank 1. This returns a bank number, not RAM capacity, an address or a pointer.

Syntax

u8 __svbk_get();

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Return value

Current effective bank number as u8, 1–7; raw selector 0 is reported as 1.

Conditions and limits

__svbk_get and __svbk_set require --cgb=cgb_only or #pragma rom_cgb cgb_only. DMG and dual-mode builds reject them with KQ2103, even if a runtime condition would skip the call. Use the guarded raw setter only when its different contract fits your program.

Switching banks changes every access in $D000–$DFFF; fixed WRAM at $C000–$CFFF stays mapped. Keep the stack and all state needed during the switch outside the switched window. The sample uses --stack-bank=fixed and explicitly located fixed-WRAM state. Coordinate interrupts and banked DMA with the switch; these APIs add no critical section.

Usage example

if (__svbk_get()!=1) failures++; // Normalize raw selector zero to effective bank 1.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The complete CGB-only program stores 1 at $D100 in WRAM bank 2 and 2 at the same address in bank 3, then reads both back and restores bank 1. The values choose an 8 × 8 red square at (16,24) and a blue one-pixel 8 × 8 square outline at (16,48). FAILED CHECKS 000 checks raw-selector normalization, bank separation and the previous-bank return for constant, variable, arithmetic and function-result arguments. Six separate invalid-build fixtures verify KQ2103 for DMG/dual targets and KQ2102 for constant banks 0 and 8. Runtime verification uses KOKURA; real hardware and interrupt-driven concurrent bank changes are not tested.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_wram_banks.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_wram_banks.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb_only --no-cache --no-disasm

{
                if (args.Length != 0) Error(expr, "__svbk_get() expects 0 arguments");
                if (!Program.IsCgbOnlyTargetRequested())
                    Error(expr, ErrorCode.BankedWramRequiresCgbOnly, "__svbk_get() requires #pragma rom_cgb cgb_only or --cgb=cgb_only");
                EmitReadNormalizedSvbkIntoA();
                return;
            }

            // Select a WRAM bank and return the prior normalized bank; diagnose out-of-range constant requests.
            if (funcName == "__svbk_set")
            {
                if (args.Length != 1) Error(expr, "__svbk_set(bank_u8) expects 1 argument");
                if (!Program.IsCgbOnlyTargetRequested())
                    Error(expr, ErrorCode.BankedWramRequiresCgbOnly, "__svbk_set() requires #pragma rom_cgb cgb_only or --cgb=cgb_only");

                Expr bankExpr = FoldConstants(args[0]);
                if (bankExpr.Match(Tag.Integer, out int bankLiteral) && (bankLiteral < 1 || bankLiteral > 7))
                    Error(expr, ErrorCode.InvalidWramXBank, "__svbk_set() bank must be in range 1..7 (got {0})", bankLiteral);

                EmitReadNormalizedSvbkIntoA();
                EmitAsm("LD_B_A");
                CompileIntoA(bankExpr);
                EmitAsm("LDH_MEM_A", new AsmOperand(0x70, AddressMode.HighMem));
                EmitAsm("LD_A_B");
                return;
            }

            // __cgb_safe_set_* (safe CGB-only register write wrappers)
            if (TryGetCgbSafeRegister(funcName, out int cgbOffset, out string cgbReg))
            {

Switch the WRAM bank mapped at $D000–$DFFF and return the effective bank selected before the switch. Save this return value if you need to restore the caller's bank. The memory contents are not copied or cleared, and the function does not restore the bank automatically.

Syntax

u8 __svbk_set(u8 bank);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

bank

Requested bank as u8, 1–7. Constant values outside this range produce KQ2102. Dynamic values are not range-checked by this intrinsic; validate them before calling rather than relying on register masking.

Return value

Effective bank number before the switch as u8, 1–7. This is the old bank, not the newly selected bank.

Conditions and limits

__svbk_get and __svbk_set require --cgb=cgb_only or #pragma rom_cgb cgb_only. DMG and dual-mode builds reject them with KQ2103, even if a runtime condition would skip the call. Use the guarded raw setter only when its different contract fits your program.

Switching banks changes every access in $D000–$DFFF; fixed WRAM at $C000–$CFFF stays mapped. Keep the stack and all state needed during the switch outside the switched window. The sample uses --stack-bank=fixed and explicitly located fixed-WRAM state. Coordinate interrupts and banked DMA with the switch; these APIs add no critical section.

Usage example

previous_bank=__svbk_set(requested_bank);
if(previous_bank!=1 || __svbk_get()!=2) failures++;
*((u8*)0xD100)=1; // This byte belongs to bank 2.
previous_bank=__svbk_set(next_bank()); // Dynamic argument evaluates to 3.
if(previous_bank!=2 || __svbk_get()!=3) failures++;
*((u8*)0xD100)=2; // Same CPU address, different physical RAM.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The complete CGB-only program stores 1 at $D100 in WRAM bank 2 and 2 at the same address in bank 3, then reads both back and restores bank 1. The values choose an 8 × 8 red square at (16,24) and a blue one-pixel 8 × 8 square outline at (16,48). FAILED CHECKS 000 checks raw-selector normalization, bank separation and the previous-bank return for constant, variable, arithmetic and function-result arguments. Six separate invalid-build fixtures verify KQ2103 for DMG/dual targets and KQ2102 for constant banks 0 and 8. Runtime verification uses KOKURA; real hardware and interrupt-driven concurrent bank changes are not tested.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_wram_banks.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_wram_banks.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb_only --no-cache --no-disasm

{
                if (args.Length != 1) Error(expr, "__svbk_set(bank_u8) expects 1 argument");
                if (!Program.IsCgbOnlyTargetRequested())
                    Error(expr, ErrorCode.BankedWramRequiresCgbOnly, "__svbk_set() requires #pragma rom_cgb cgb_only or --cgb=cgb_only");

                Expr bankExpr = FoldConstants(args[0]);
                if (bankExpr.Match(Tag.Integer, out int bankLiteral) && (bankLiteral < 1 || bankLiteral > 7))
                    Error(expr, ErrorCode.InvalidWramXBank, "__svbk_set() bank must be in range 1..7 (got {0})", bankLiteral);

                EmitReadNormalizedSvbkIntoA();
                EmitAsm("LD_B_A");
                CompileIntoA(bankExpr);
                EmitAsm("LDH_MEM_A", new AsmOperand(0x70, AddressMode.HighMem));
                EmitAsm("LD_A_B");
                return;
            }

            // __cgb_safe_set_* (safe CGB-only register write wrappers)
            if (TryGetCgbSafeRegister(funcName, out int cgbOffset, out string cgbReg))
            {
                if (args.Length != 1) Program.Error(funcName + "(value_u8) expects 1 argument");

                if (IsKnownCgbRuntimeTrue())
                {
                    CompileIntoA(args[0]);
                    if (cgbOffset == 0x4F)
                        EmitAsm("AND_IMM", new AsmOperand(0x01, AddressMode.Immediate));
                    EmitAsm("LDH_MEM_A", new AsmOperand(cgbOffset, AddressMode.HighMem));
                    CgbGuardedWriteCount++;
                    CgbGuardedRegisters.Add(cgbReg);
                    return;

Copy len bytes from src to dst immediately, in increasing address order. The function returns after the copy finishes; it does not enqueue work. Source and destination advance by one byte, without tilemap row strides or tile-format conversion.

Syntax

void __vram_memcpy_unsafe(u16 dst, const void* src, u16 len);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

dst

First destination byte address, normally in VRAM 0x8000–0x9FFF. Keep the entire span valid. CGB uses the current VRAM bank; bank 0 contains tile numbers and bank 1 contains map attributes. These routines do not choose a map from LCDC, wrap rows or allocate VRAM.

src

Source byte pointer, valid and mapped for the whole call. Data is read immediately; it is not retained for a later flush. The source bank is not switched automatically. Use non-overlapping spans: this forward copy does not provide memmove semantics.

len

Number of consecutive bytes, 0–65535. It is not a tile count. Keep the complete address range inside valid source and writable destination storage; the API does not check bounds or prevent 16-bit address wrap.

Return value

None (void).

Conditions and limits

Skip all LCD/STAT waiting and write directly with the CPU. Keep the LCD off, or ensure the entire transfer fits in a writable interval you control. Merely entering VBlank does not make an arbitrarily long transfer safe. This intrinsic emits neither DI nor EI for the transfer and provides no clipping or bounds checks.

Usage example

// The LCD is off throughout these unchecked writes.
__vram_memcpy_unsafe(0x98C2,strip,computed_length());

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This example uses __vram_memcpy_unsafe to place three map bytes at tile (2,6), pixel (16,48). Expect the three patterns [1,2,3] from left to right in a 24 × 8 area. Neighboring cells must remain blank. The full program places each tested copy or fill on its own row.

The supplied original graphics use tile 1 for a solid 8 × 8 square, tile 2 for its left four columns, and tile 3 for a left-aligned triangle that widens by one pixel per row from 1 to 8 pixels. DMG uses black on white; CGB distinguishes the operations with colors while keeping text black.

The square at pixel (16,88) must remain after zero-length safe and unsafe calls. With the LCD on, safe copy and fill add squares at (16,96) and (32,96). FAILED CHECKS must read 000. The emulator tests compare the drawn pixels as well as the counter. CGB uses bank 0 in this example; other banks and physical hardware are not tested here.

In CGB mode, the operation rows from MEMCPY through FILL UNSAFE cycle through red, blue and green. The ZERO COUNT square is red. In LCD ON, the left square is blue and the right square is green. Text stays black. The checks verify these colors at every drawn pixel.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\vram_memory_shapes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\vram_memory_shapes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

{
                if (args.Length != 3) Error(expr, "__vram_memcpy_unsafe(dst, src, len) expects 3 arguments");

                CompileIntoHL(args[0]); EmitAsm("PUSH_HL"); // dst
                CompileIntoHL(args[1]); EmitAsm("PUSH_HL"); // src
                // Use the same count specialization without emitting LCD-mode waits.
                Expr vramCopyUnsafeLen = FoldConstants(args[2]);
                EmitLengthExprIntoBC(vramCopyUnsafeLen);
                EmitAsm("POP_DE"); // src
                EmitAsm("POP_HL"); // dst

                if (vramCopyUnsafeLen.Match(Tag.Integer, out int vramCopyUnsafeLenConst) &&
                    TryEmitVramMemcpyConstCount(false, vramCopyUnsafeLenConst, "vramcpyu_small"))
                    return;

                AsmOperand vcuLoop = MakeUniqueLabel("vramcpyu_loop");
                AsmOperand vcuDone = MakeUniqueLabel("vramcpyu_done");
                EmitLabel(vcuLoop);
                EmitAsm("LD_A_B");
                EmitAsm("OR_C");
                EmitAsm("JR_Z", vcuDone);
                EmitAsm("LD_A_DE");
                EmitAsm("LDI_HL_A");
                EmitAsm("INC_DE");
                EmitAsm("DEC_BC");
                EmitAsm("JR", vcuLoop);
                EmitLabel(vcuDone);
                return;
            }

            // __vram_memset(dst_ptr, value_u8, len_u16)
            // Safe VRAM fill: if LCD is on, each byte write is gated by STAT mode 0/1.
            if (funcName == "__vram_memset")
            {
                if (args.Length != 3) Error(expr, "__vram_memset(dst, value, l

Immediately fill len consecutive bytes starting at dst with the byte value. This repeats one byte, not a whole tile pattern. A map-byte fill repeats a tile number; a pattern-byte fill instead changes the encoded pixel planes.

Syntax

void __vram_memset_unsafe(u16 dst, u8 value, u16 len);

The parameter names in this call syntax explain the compiler intrinsic; they are not a separate C prototype.

Parameters

dst

First destination byte address, normally in VRAM 0x8000–0x9FFF. Keep the entire span valid. CGB uses the current VRAM bank; bank 0 contains tile numbers and bank 1 contains map attributes. These routines do not choose a map from LCDC, wrap rows or allocate VRAM.

value

One byte, 0–255, written repeatedly. Its visible meaning depends on whether the destination contains tile indices, pixel planes or another byte-based structure.

len

Number of consecutive bytes, 0–65535. It is not a tile count. Keep the complete address range inside valid source and writable destination storage; the API does not check bounds or prevent 16-bit address wrap.

Return value

None (void).

Conditions and limits

Skip all LCD/STAT waiting and write directly with the CPU. Keep the LCD off, or ensure the entire transfer fits in a writable interval you control. Merely entering VBlank does not make an arbitrarily long transfer safe. This intrinsic emits neither DI nor EI for the transfer and provides no clipping or bounds checks.

Usage example

__vram_memset_unsafe(0x9942,1,computed_length()); // Safe here because the LCD is off.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This example uses __vram_memset_unsafe to fill three map bytes at tile (2,10), pixel (16,80), with tile number 1. Expect a solid 24 × 8 bar with blank neighboring cells. The count is computed from variables or a function result; all three bytes must still receive value 1.

The supplied original graphics use tile 1 for a solid 8 × 8 square, tile 2 for its left four columns, and tile 3 for a left-aligned triangle that widens by one pixel per row from 1 to 8 pixels. DMG uses black on white; CGB distinguishes the operations with colors while keeping text black.

The square at pixel (16,88) must remain after zero-length safe and unsafe calls. With the LCD on, safe copy and fill add squares at (16,96) and (32,96). FAILED CHECKS must read 000. The emulator tests compare the drawn pixels as well as the counter. CGB uses bank 0 in this example; other banks and physical hardware are not tested here.

In CGB mode, the operation rows from MEMCPY through FILL UNSAFE cycle through red, blue and green. The ZERO COUNT square is red. In LCD ON, the left square is blue and the right square is green. Text stays black. The checks verify these colors at every drawn pixel.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\vram_memory_shapes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\vram_memory_shapes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

{
                if (args.Length != 3) Error(expr, "__vram_memset_unsafe(dst, value, len) expects 3 arguments");

                CompileIntoHL(args[0]); EmitAsm("PUSH_HL"); // dst
                CompileIntoA(args[1]); EmitAsm("LD_D_A"); // value
                // Specialize a constant unsafe fill or fall back to its unchecked byte loop.
                Expr vramSetUnsafeLen = FoldConstants(args[2]);
                EmitLengthExprIntoBC(vramSetUnsafeLen);
                EmitAsm("POP_HL"); // dst

                if (vramSetUnsafeLen.Match(Tag.Integer, out int vramSetUnsafeLenConst) &&
                    TryEmitVramMemsetConstCount(false, vramSetUnsafeLenConst, "vramsetu_small"))
                    return;

                AsmOperand vsuLoop = MakeUniqueLabel("vramsetu_loop");
                AsmOperand vsuDone = MakeUniqueLabel("vramsetu_done");
                EmitLabel(vsuLoop);
                EmitAsm("LD_A_B");
                EmitAsm("OR_C");
                EmitAsm("JR_Z", vsuDone);
                EmitAsm("LD_A_D");
                EmitAsm("LDI_HL_A");
                EmitAsm("DEC_BC");
                EmitAsm("JR", vsuLoop);
                EmitLabel(vsuDone);
                return;
            }

            // __far_memcpy(dst_ptr, bank_u8, src_ptr, len_u16)
            // Copies from switchable ROM bank via a bank0 helper and restores original bank.
            if (funcName == "__far_memcpy")
            {
                if (args.Length != 4) Error(expr, "__far_memcpy(dst, bank, src, len) expects 4 arguments");

                CompileIntoHL(

With LCD running, wait until LY equals the target line.

Syntax

void __wait_ly(u8 ly);

Parameters

ly

Scanline 0..153; values above 153 do not complete while the LCD runs.

Return value

No return value.

Conditions and limits

Returns immediately on the target line; if that line has passed, waits until the next frame. Also returns immediately with LCD off.

Usage example

M_LCDC=0x91;__wait_ly(80);result[9]=*((u8*)0xFF44);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Learn map selection, scrolling, nesting and scanline waits. Bases are 38912/39936; nested tokens are 0/1; observed target LY values are 80/144. Also verify waits return with the LCD off.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch3_display.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch3_display.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --ramsize=none

if (funcName == "__wait_ly")
            {
                if (args.Length != 1) Error(expr, "__wait_ly(target) expects 1 argument");

                CompileIntoA(args[0]);
                EmitAsm("LD_B_A");

                AsmOperand wlyLoop = MakeUniqueLabel("waitly_loop");
                AsmOperand wlyDone = MakeUniqueLabel("waitly_done");

                // If LCD is off, LY is not meaningful; return.
                EmitAsm("LDH_A_MEM", new AsmOperand(0x40, AddressMode.HighMem)); // LCDC
                EmitAsm("AND_IMM", new AsmOperand(0x80, AddressMode.Immediate));
                EmitAsm("JR_Z", wlyDone);

                EmitLabel(wlyLoop);
                EmitAsm("LDH_A_MEM", new AsmOperand(0x44, AddressMode.HighMem)); // LY
                EmitAsm("CP_B");
                EmitAsm("JR_NZ", wlyLoop);
                EmitLabel(wlyDone);
                return;
            }

Multiply a signed 16-bit value by a signed 8-bit coefficient, divide by 256 and truncate toward zero.

Syntax

s16 __smul16x8(s16 a, s8 b);

Parameters

a

Signed 16-bit value to scale.

b

Signed byte coefficient in -128..127.

Return value

Returns the signed 16-bit scaled product.

Conditions and limits

The coefficient range is -128..127, scaled with 256 representing 1.0. Products truncate toward zero for either sign: -257*64/256 returns -64.

Usage example

result[13]=__smul16x8(-257,64);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Left shows the initial state; right shows one tick later. A red 16x16 box with center (24,24) and velocity (4,16) reaches (28,36), with Y velocity zero on the blue floor. Panel origins are screen (8,48) and (88,48). DMG renders all marks in black. RAM checks also cover initialization, setters, integration, rectangle/point queries and signed scaling.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\physics_body2d.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\physics_body2d.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Multiply a signed word by a signed byte; divide by 256, truncating toward zero.

if (funcName == "__smul16x8")
            {
                if (args.Length != 2) Error(expr, "__smul16x8 requires 2 arguments");

                EmitDotTermToHL(args[0], args[1], signed: true, q1_7: false, labelPrefix: "__smul16x8");
                LastCallReturnsHL = true;
                return;
            }

Clear the selected flag to 0 without clearing the rest of its byte. Use this to remove one stored condition, such as a temporary status flag. Clearing the same bit again still leaves it at 0.

Syntax

void __bit_clear(u8* p, u16 bit_index);

Parameters

p

Pointer to the first byte of the flag array in CPU-accessible memory. The array is not allocated or initialized by this call. Use writable RAM for set, clear and toggle operations; the test operation only reads it.

bit_index

Zero-based bit index as u16 (0–65535), not a byte offset or a bit mask. Index 0 selects mask 0x01 in byte 0; index 7 selects 0x80 in byte 0; index 8 selects 0x01 in byte 1. In general, the byte offset is index / 8 and the mask is 1 << (index % 8). For an N-byte array, require index < 8*N and a valid CPU address range.

Return value

None (void).

Conditions and limits

The caller must provide enough storage. There is no array-length argument, bounds clipping, bank switching or automatic graphics upload. A large bit number can select a byte well beyond the allocated array. Keep the memory mapping stable; do not use these RAM-flag helpers as a shortcut for hardware registers whose reads or writes have side effects.

Set, clear and toggle read a byte, modify the selected bit, then write the byte back. This sequence is not an atomic update. Coordinate writers in the main loop and interrupt handlers so that an intervening update to another bit in the same byte is not lost.

Usage example

__bit_clear(bit_flags,2);
bit_clear_value=bit_flags[0]; // A6 & FB = A2, decimal 162.
__bit_clear(bit_flags,2);     // Clearing it twice leaves it clear.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The complete program reaches this step with byte 0 equal to 0xA6. Clearing bit 2 changes it to 0xA2 (binary 10100010, decimal 162); the CLEAR BIT2 row must show 162. Clearing bit 2 again leaves the result unchanged. The other stored flags survive both calls.

Expected GB rows, in decimal: TEST OFF 000, TEST ON 001, SET BIT1 166, CLEAR BIT2 162, TOGGLE BIT7 034, RESTORE 162, NEXT BYTE 130, FAILED 000. NEXT BYTE comes from setting index 9 in the second byte, changing 0x80 to 0x82 without modifying byte 0. DMG uses black text on white; CGB uses blue text on white.

The program checks every displayed transition and shows the number of failures. Set, clear and toggle themselves return no value; their rows display the resulting RAM byte. Separate emulator checks compare all 520 bytes of guarded buffers in 136 cases per platform, including constant and runtime indices across byte and 256-byte boundaries and all eight possible nonzero bit-test masks. These are RAM-state checks, not a drawing demonstration. Physical hardware and concurrent interrupt writers have not been tested.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\bit_intrinsics.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\bit_intrinsics.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

if (funcName == "__bit_test" || funcName == "__bit_set" || funcName == "__bit_clear" || funcName == "__bit_toggle")
            {
                if (args.Length != 2) Error(expr, funcName + "(ptr, bit_index) expects 2 arguments");

                CompileIntoHL(args[0]); EmitAsm("PUSH_HL"); // ptr
                CompileIntoHL(args[1]); EmitAsm("PUSH_HL"); // bit_index

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(0, AddressMode.Relative));
                EmitAsm("LD_A_HL");
                EmitAsm("AND_IMM", new AsmOperand(7, AddressMode.Immediate));
                EmitAsm("LD_B_A"); // bit number 0..7

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(0, AddressMode.Relative));
                EmitAsm("LD_A_HL");
                EmitAsm("LD_E_A");
                EmitAsm("INC_HL");
                EmitAsm("LD_A_HL");
                EmitAsm("LD_D_A");
                EmitAsm("LD_H_D");
                EmitAsm("LD_L_E");
                EmitShiftRightLogicalHL(3);
                EmitAsm("PUSH_HL"); // byte offset

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                EmitAsm("LD_A_HL");
                EmitAsm("LD_E_A");
                EmitAsm("INC_HL");
                EmitAsm("LD_A_HL");
                EmitAsm("LD_D_A");

                EmitAsm("POP_HL");
                EmitAsm("ADD_HL_DE"); // HL = ptr + (bit_index >> 3)

                AsmOperand maskReady = MakeUniqueLabel("bit_mask_ready");
                AsmOperand maskLoop = MakeUniqueLabel("bit_mask_loop");
                EmitAsm("LD_A_B");
                EmitAsm("OR_A");
                EmitAsm("LD_A_IMM", new AsmOperand(1, AddressMode.Immediate));
                EmitAsm("JR_Z", maskReady);
                EmitLabel(maskLoop);
                EmitAsm("ADD_A");
                EmitAsm("DEC_B");
                EmitAsm("JR_NZ", maskLoop);
                EmitLabel(maskReady);
                EmitAsm("LD_B_A"); // mask

                if (funcName == "__bit_test")
                {
                    AsmOperand retZero = MakeUniqueLabel("bit_test_zero");
                    AsmOperand done = MakeUniqueLabel("bit_test_done");
                    EmitAsm("LD_A_HL");
                    EmitAsm("AND_B");
                    EmitAsm("JR_Z", retZero);
                    EmitAsm("LD_A_IMM", new AsmOperand(1, AddressMode.Immediate));
                    EmitAsm("JR", done);
                    EmitLabel(retZero);
                    EmitAsm("XOR_A");
                    EmitLabel(done);
                    EmitAsm("ADD_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                    return;
                }

                if (funcName == "__bit_set")
                {
                    EmitAsm("LD_A_HL");
                    EmitAsm("OR_B");
                    EmitAsm("LD_HL_A");
                    EmitAsm("ADD_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                    return;
                }

                if (funcName == "__bit_clear")
                {
                    EmitAsm("LD_A_B");
                    EmitAsm("CPL");
                    EmitAsm("LD_B_A");
                    EmitAsm("LD_A_HL");
                    EmitAsm("AND_B");
                    EmitAsm("LD_HL_A");
                    EmitAsm("ADD_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                    return;
                }

                EmitAsm("LD_A_HL");
                EmitAsm("XOR_B");
                EmitAsm("LD_HL_A");
                EmitAsm("ADD_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                return;
            }

Set the selected flag to 1 while preserving the other seven bits in the same byte. For example, mark a quest as completed or an item as collected. Setting a bit that is already 1 leaves it unchanged; this is not a toggle.

Syntax

void __bit_set(u8* p, u16 bit_index);

Parameters

p

Pointer to the first byte of the flag array in CPU-accessible memory. The array is not allocated or initialized by this call. Use writable RAM for set, clear and toggle operations; the test operation only reads it.

bit_index

Zero-based bit index as u16 (0–65535), not a byte offset or a bit mask. Index 0 selects mask 0x01 in byte 0; index 7 selects 0x80 in byte 0; index 8 selects 0x01 in byte 1. In general, the byte offset is index / 8 and the mask is 1 << (index % 8). For an N-byte array, require index < 8*N and a valid CPU address range.

Return value

None (void).

Conditions and limits

The caller must provide enough storage. There is no array-length argument, bounds clipping, bank switching or automatic graphics upload. A large bit number can select a byte well beyond the allocated array. Keep the memory mapping stable; do not use these RAM-flag helpers as a shortcut for hardware registers whose reads or writes have side effects.

Set, clear and toggle read a byte, modify the selected bit, then write the byte back. This sequence is not an atomic update. Coordinate writers in the main loop and interrupt handlers so that an intervening update to another bit in the same byte is not lost.

Usage example

__bit_set(bit_flags,1);
bit_set_value=bit_flags[0]; // A4 | 02 = A6, decimal 166.
__bit_set(bit_flags,1);     // Setting it twice leaves it set.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Set bit 1 of 0xA4: 10100100 | 00000010 becomes 10100110, or 0xA6 (decimal 166). The SET BIT1 row must show 166. The sample sets the bit a second time and verifies that the byte remains 0xA6, demonstrating that repeated setting does not invert a flag.

Expected GB rows, in decimal: TEST OFF 000, TEST ON 001, SET BIT1 166, CLEAR BIT2 162, TOGGLE BIT7 034, RESTORE 162, NEXT BYTE 130, FAILED 000. NEXT BYTE comes from setting index 9 in the second byte, changing 0x80 to 0x82 without modifying byte 0. DMG uses black text on white; CGB uses blue text on white.

The program checks every displayed transition and shows the number of failures. Set, clear and toggle themselves return no value; their rows display the resulting RAM byte. Separate emulator checks compare all 520 bytes of guarded buffers in 136 cases per platform, including constant and runtime indices across byte and 256-byte boundaries and all eight possible nonzero bit-test masks. These are RAM-state checks, not a drawing demonstration. Physical hardware and concurrent interrupt writers have not been tested.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\bit_intrinsics.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\bit_intrinsics.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

if (funcName == "__bit_test" || funcName == "__bit_set" || funcName == "__bit_clear" || funcName == "__bit_toggle")
            {
                if (args.Length != 2) Error(expr, funcName + "(ptr, bit_index) expects 2 arguments");

                CompileIntoHL(args[0]); EmitAsm("PUSH_HL"); // ptr
                CompileIntoHL(args[1]); EmitAsm("PUSH_HL"); // bit_index

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(0, AddressMode.Relative));
                EmitAsm("LD_A_HL");
                EmitAsm("AND_IMM", new AsmOperand(7, AddressMode.Immediate));
                EmitAsm("LD_B_A"); // bit number 0..7

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(0, AddressMode.Relative));
                EmitAsm("LD_A_HL");
                EmitAsm("LD_E_A");
                EmitAsm("INC_HL");
                EmitAsm("LD_A_HL");
                EmitAsm("LD_D_A");
                EmitAsm("LD_H_D");
                EmitAsm("LD_L_E");
                EmitShiftRightLogicalHL(3);
                EmitAsm("PUSH_HL"); // byte offset

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                EmitAsm("LD_A_HL");
                EmitAsm("LD_E_A");
                EmitAsm("INC_HL");
                EmitAsm("LD_A_HL");
                EmitAsm("LD_D_A");

                EmitAsm("POP_HL");
                EmitAsm("ADD_HL_DE"); // HL = ptr + (bit_index >> 3)

                AsmOperand maskReady = MakeUniqueLabel("bit_mask_ready");
                AsmOperand maskLoop = MakeUniqueLabel("bit_mask_loop");
                EmitAsm("LD_A_B");
                EmitAsm("OR_A");
                EmitAsm("LD_A_IMM", new AsmOperand(1, AddressMode.Immediate));
                EmitAsm("JR_Z", maskReady);
                EmitLabel(maskLoop);
                EmitAsm("ADD_A");
                EmitAsm("DEC_B");
                EmitAsm("JR_NZ", maskLoop);
                EmitLabel(maskReady);
                EmitAsm("LD_B_A"); // mask

                if (funcName == "__bit_test")
                {
                    AsmOperand retZero = MakeUniqueLabel("bit_test_zero");
                    AsmOperand done = MakeUniqueLabel("bit_test_done");
                    EmitAsm("LD_A_HL");
                    EmitAsm("AND_B");
                    EmitAsm("JR_Z", retZero);
                    EmitAsm("LD_A_IMM", new AsmOperand(1, AddressMode.Immediate));
                    EmitAsm("JR", done);
                    EmitLabel(retZero);
                    EmitAsm("XOR_A");
                    EmitLabel(done);
                    EmitAsm("ADD_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                    return;
                }

                if (funcName == "__bit_set")
                {
                    EmitAsm("LD_A_HL");
                    EmitAsm("OR_B");
                    EmitAsm("LD_HL_A");
                    EmitAsm("ADD_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                    return;
                }

                if (funcName == "__bit_clear")
                {
                    EmitAsm("LD_A_B");
                    EmitAsm("CPL");
                    EmitAsm("LD_B_A");
                    EmitAsm("LD_A_HL");
                    EmitAsm("AND_B");
                    EmitAsm("LD_HL_A");
                    EmitAsm("ADD_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                    return;
                }

                EmitAsm("LD_A_HL");
                EmitAsm("XOR_B");
                EmitAsm("LD_HL_A");
                EmitAsm("ADD_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                return;
            }

Read one flag from a packed array of bits without modifying the array. This lets eight independent on/off flags share each byte of RAM. The result tells you whether the selected bit is clear or set; its numeric representation depends on the target.

Syntax

u8 __bit_test(const u8* p, u16 bit_index);

Parameters

p

Pointer to the first byte of the flag array in CPU-accessible memory. The array is not allocated or initialized by this call. Use writable RAM for set, clear and toggle operations; the test operation only reads it.

bit_index

Zero-based bit index as u16 (0–65535), not a byte offset or a bit mask. Index 0 selects mask 0x01 in byte 0; index 7 selects 0x80 in byte 0; index 8 selects 0x01 in byte 1. In general, the byte offset is index / 8 and the mask is 1 << (index % 8). For an N-byte array, require index < 8*N and a valid CPU address range.

Return value

u8: exactly 0 when the bit is clear, or 1 when it is set. The GB implementation normalizes the masked byte to these two values.

Conditions and limits

The caller must provide enough storage. There is no array-length argument, bounds clipping, bank switching or automatic graphics upload. A large bit number can select a byte well beyond the allocated array. Keep the memory mapping stable; do not use these RAM-flag helpers as a shortcut for hardware registers whose reads or writes have side effects.

Usage example

bit_off=__bit_test(bit_flags,1); // Bit 1 of A4 is clear: zero.
bit_on=__bit_test(bit_flags,7);  // Bit 7 is set: GB returns 1; FC returns 128.
bit_is_on=0;
if(bit_on!=0)bit_is_on=1; // The same nonzero test works on both targets.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Start with byte 0 equal to 0xA4 (binary 10100100). Testing bit 1 returns 0. Testing bit 7 returns 1 on GB or 128 on FC; the sample also converts that nonzero result to a shared on/off flag and checks that the original byte is unchanged. Look at TEST OFF and TEST ON in the screen below.

Expected GB rows, in decimal: TEST OFF 000, TEST ON 001, SET BIT1 166, CLEAR BIT2 162, TOGGLE BIT7 034, RESTORE 162, NEXT BYTE 130, FAILED 000. NEXT BYTE comes from setting index 9 in the second byte, changing 0x80 to 0x82 without modifying byte 0. DMG uses black text on white; CGB uses blue text on white.

The program checks every displayed transition and shows the number of failures. Set, clear and toggle themselves return no value; their rows display the resulting RAM byte. Separate emulator checks compare all 520 bytes of guarded buffers in 136 cases per platform, including constant and runtime indices across byte and 256-byte boundaries and all eight possible nonzero bit-test masks. These are RAM-state checks, not a drawing demonstration. Physical hardware and concurrent interrupt writers have not been tested.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\bit_intrinsics.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\bit_intrinsics.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

if (funcName == "__bit_test" || funcName == "__bit_set" || funcName == "__bit_clear" || funcName == "__bit_toggle")
            {
                if (args.Length != 2) Error(expr, funcName + "(ptr, bit_index) expects 2 arguments");

                CompileIntoHL(args[0]); EmitAsm("PUSH_HL"); // ptr
                CompileIntoHL(args[1]); EmitAsm("PUSH_HL"); // bit_index

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(0, AddressMode.Relative));
                EmitAsm("LD_A_HL");
                EmitAsm("AND_IMM", new AsmOperand(7, AddressMode.Immediate));
                EmitAsm("LD_B_A"); // bit number 0..7

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(0, AddressMode.Relative));
                EmitAsm("LD_A_HL");
                EmitAsm("LD_E_A");
                EmitAsm("INC_HL");
                EmitAsm("LD_A_HL");
                EmitAsm("LD_D_A");
                EmitAsm("LD_H_D");
                EmitAsm("LD_L_E");
                EmitShiftRightLogicalHL(3);
                EmitAsm("PUSH_HL"); // byte offset

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                EmitAsm("LD_A_HL");
                EmitAsm("LD_E_A");
                EmitAsm("INC_HL");
                EmitAsm("LD_A_HL");
                EmitAsm("LD_D_A");

                EmitAsm("POP_HL");
                EmitAsm("ADD_HL_DE"); // HL = ptr + (bit_index >> 3)

                AsmOperand maskReady = MakeUniqueLabel("bit_mask_ready");
                AsmOperand maskLoop = MakeUniqueLabel("bit_mask_loop");
                EmitAsm("LD_A_B");
                EmitAsm("OR_A");
                EmitAsm("LD_A_IMM", new AsmOperand(1, AddressMode.Immediate));
                EmitAsm("JR_Z", maskReady);
                EmitLabel(maskLoop);
                EmitAsm("ADD_A");
                EmitAsm("DEC_B");
                EmitAsm("JR_NZ", maskLoop);
                EmitLabel(maskReady);
                EmitAsm("LD_B_A"); // mask

                if (funcName == "__bit_test")
                {
                    AsmOperand retZero = MakeUniqueLabel("bit_test_zero");
                    AsmOperand done = MakeUniqueLabel("bit_test_done");
                    EmitAsm("LD_A_HL");
                    EmitAsm("AND_B");
                    EmitAsm("JR_Z", retZero);
                    EmitAsm("LD_A_IMM", new AsmOperand(1, AddressMode.Immediate));
                    EmitAsm("JR", done);
                    EmitLabel(retZero);
                    EmitAsm("XOR_A");
                    EmitLabel(done);
                    EmitAsm("ADD_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                    return;
                }

                if (funcName == "__bit_set")
                {
                    EmitAsm("LD_A_HL");
                    EmitAsm("OR_B");
                    EmitAsm("LD_HL_A");
                    EmitAsm("ADD_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                    return;
                }

                if (funcName == "__bit_clear")
                {
                    EmitAsm("LD_A_B");
                    EmitAsm("CPL");
                    EmitAsm("LD_B_A");
                    EmitAsm("LD_A_HL");
                    EmitAsm("AND_B");
                    EmitAsm("LD_HL_A");
                    EmitAsm("ADD_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                    return;
                }

                EmitAsm("LD_A_HL");
                EmitAsm("XOR_B");
                EmitAsm("LD_HL_A");
                EmitAsm("ADD_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                return;
            }

Invert the selected flag: 0 becomes 1 and 1 becomes 0. The remaining bits are preserved. Two calls on the same bit restore its original state, provided nothing else writes that bit between the calls.

Syntax

void __bit_toggle(u8* p, u16 bit_index);

Parameters

p

Pointer to the first byte of the flag array in CPU-accessible memory. The array is not allocated or initialized by this call. Use writable RAM for set, clear and toggle operations; the test operation only reads it.

bit_index

Zero-based bit index as u16 (0–65535), not a byte offset or a bit mask. Index 0 selects mask 0x01 in byte 0; index 7 selects 0x80 in byte 0; index 8 selects 0x01 in byte 1. In general, the byte offset is index / 8 and the mask is 1 << (index % 8). For an N-byte array, require index < 8*N and a valid CPU address range.

Return value

None (void).

Conditions and limits

The caller must provide enough storage. There is no array-length argument, bounds clipping, bank switching or automatic graphics upload. A large bit number can select a byte well beyond the allocated array. Keep the memory mapping stable; do not use these RAM-flag helpers as a shortcut for hardware registers whose reads or writes have side effects.

Set, clear and toggle read a byte, modify the selected bit, then write the byte back. This sequence is not an atomic update. Coordinate writers in the main loop and interrupt handlers so that an intervening update to another bit in the same byte is not lost.

Usage example

__bit_toggle(bit_flags,7);
bit_toggle_value=bit_flags[0]; // A2 ^ 80 = 22, decimal 34.
__bit_toggle(bit_flags,7);
bit_restore_value=bit_flags[0]; // Two toggles restore A2.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The complete program enters this step with 0xA2. Toggling bit 7 produces 0x22 (decimal 34), so TOGGLE BIT7 shows 034. Toggling it again restores 0xA2, and RESTORE shows 162. These two observations demonstrate both directions of the inversion while preserving the other bits.

Expected GB rows, in decimal: TEST OFF 000, TEST ON 001, SET BIT1 166, CLEAR BIT2 162, TOGGLE BIT7 034, RESTORE 162, NEXT BYTE 130, FAILED 000. NEXT BYTE comes from setting index 9 in the second byte, changing 0x80 to 0x82 without modifying byte 0. DMG uses black text on white; CGB uses blue text on white.

The program checks every displayed transition and shows the number of failures. Set, clear and toggle themselves return no value; their rows display the resulting RAM byte. Separate emulator checks compare all 520 bytes of guarded buffers in 136 cases per platform, including constant and runtime indices across byte and 256-byte boundaries and all eight possible nonzero bit-test masks. These are RAM-state checks, not a drawing demonstration. Physical hardware and concurrent interrupt writers have not been tested.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\bit_intrinsics.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\bit_intrinsics.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

if (funcName == "__bit_test" || funcName == "__bit_set" || funcName == "__bit_clear" || funcName == "__bit_toggle")
            {
                if (args.Length != 2) Error(expr, funcName + "(ptr, bit_index) expects 2 arguments");

                CompileIntoHL(args[0]); EmitAsm("PUSH_HL"); // ptr
                CompileIntoHL(args[1]); EmitAsm("PUSH_HL"); // bit_index

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(0, AddressMode.Relative));
                EmitAsm("LD_A_HL");
                EmitAsm("AND_IMM", new AsmOperand(7, AddressMode.Immediate));
                EmitAsm("LD_B_A"); // bit number 0..7

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(0, AddressMode.Relative));
                EmitAsm("LD_A_HL");
                EmitAsm("LD_E_A");
                EmitAsm("INC_HL");
                EmitAsm("LD_A_HL");
                EmitAsm("LD_D_A");
                EmitAsm("LD_H_D");
                EmitAsm("LD_L_E");
                EmitShiftRightLogicalHL(3);
                EmitAsm("PUSH_HL"); // byte offset

                EmitAsm("LD_HL_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                EmitAsm("LD_A_HL");
                EmitAsm("LD_E_A");
                EmitAsm("INC_HL");
                EmitAsm("LD_A_HL");
                EmitAsm("LD_D_A");

                EmitAsm("POP_HL");
                EmitAsm("ADD_HL_DE"); // HL = ptr + (bit_index >> 3)

                AsmOperand maskReady = MakeUniqueLabel("bit_mask_ready");
                AsmOperand maskLoop = MakeUniqueLabel("bit_mask_loop");
                EmitAsm("LD_A_B");
                EmitAsm("OR_A");
                EmitAsm("LD_A_IMM", new AsmOperand(1, AddressMode.Immediate));
                EmitAsm("JR_Z", maskReady);
                EmitLabel(maskLoop);
                EmitAsm("ADD_A");
                EmitAsm("DEC_B");
                EmitAsm("JR_NZ", maskLoop);
                EmitLabel(maskReady);
                EmitAsm("LD_B_A"); // mask

                if (funcName == "__bit_test")
                {
                    AsmOperand retZero = MakeUniqueLabel("bit_test_zero");
                    AsmOperand done = MakeUniqueLabel("bit_test_done");
                    EmitAsm("LD_A_HL");
                    EmitAsm("AND_B");
                    EmitAsm("JR_Z", retZero);
                    EmitAsm("LD_A_IMM", new AsmOperand(1, AddressMode.Immediate));
                    EmitAsm("JR", done);
                    EmitLabel(retZero);
                    EmitAsm("XOR_A");
                    EmitLabel(done);
                    EmitAsm("ADD_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                    return;
                }

                if (funcName == "__bit_set")
                {
                    EmitAsm("LD_A_HL");
                    EmitAsm("OR_B");
                    EmitAsm("LD_HL_A");
                    EmitAsm("ADD_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                    return;
                }

                if (funcName == "__bit_clear")
                {
                    EmitAsm("LD_A_B");
                    EmitAsm("CPL");
                    EmitAsm("LD_B_A");
                    EmitAsm("LD_A_HL");
                    EmitAsm("AND_B");
                    EmitAsm("LD_HL_A");
                    EmitAsm("ADD_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                    return;
                }

                EmitAsm("LD_A_HL");
                EmitAsm("XOR_B");
                EmitAsm("LD_HL_A");
                EmitAsm("ADD_SP_IMM", new AsmOperand(4, AddressMode.Relative));
                return;
            }

Copy exactly 16 bytes from src to dst, with no length argument. For example, copy one 16-byte record or one Game Boy/NES tile stored in CPU-accessible memory. The number 16 means bytes, not bits; this call does not upload graphics to the display.

Syntax

void __copy16(void* dst, const void* src);

Parameters

dst

Pointer to the first writable destination byte. Reserve enough consecutive bytes for the complete operation; no buffer is allocated for you.

src

Pointer to the first readable source byte. The entire range must remain accessible and unchanged throughout the copy.

Return value

None (void).

Conditions and limits

Use separate, non-overlapping source and destination ranges. These routines copy forward and do not provide overlap-safe memmove behavior; writing into the unread part of the source can corrupt later bytes.

The operation finishes before the caller continues. It neither switches ROM/RAM banks nor clips a range to a buffer boundary. Keep mappings stable, use valid memory ranges and coordinate access with interrupt handlers that use the same buffers.

On GB, these are ordinary CPU memory accesses. They do not wait for safe VRAM/OAM access, start DMA or select a CGB VRAM/WRAM bank. Use the dedicated graphics-transfer APIs for those jobs.

Usage example

memory_reset();
__copy16(memory_destination+1,memory_source+1);
memory_copy_16=memory_check(16,0); // Exactly 16 bytes, not 16 bits.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This example uses __copy16 to copy 16 patterned bytes starting at offset 1. memory_check compares the entire source and destination arrays; the COPY16 row must show 016. Starting inside the buffer leaves a leading guard byte, and bytes after the payload must also remain unchanged.

The complete program resets two 264-byte buffers before each operation, then checks every source byte, every destination byte and the untouched guard regions. The expected rows are COPY WORD 257, FILL WORD 257, COPY BYTE 255, FILL BYTE 255, COPY16 016, COPY32 032, ZERO CALLS 002 and FAILED 000. WORD/BYTE describe the count width, not the size of each copied item. The numbers are produced by the sample's checks, not return values from these void functions.

The captured screens show black lettering on white for DMG, blue on white for CGB and blue on black for FC. This example verifies RAM operations; the lettering presents the results rather than demonstrating a drawing primitive. Separate emulator checks cover 88 memory cases on each platform, including constant and runtime lengths at 0, 1, 16, 17, 32, 33, 64, 65 and 255 bytes, plus 256 and 257 for the word-count forms. Physical hardware has not been tested.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\memory_intrinsics.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\memory_intrinsics.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

if (funcName == "__copy16" || funcName == "__copy32")
            {
                if (args.Length != 2) Error(expr, funcName + "(dst, src) expects 2 arguments");

                int copyLen = (funcName == "__copy16") ? 16 : 32;
                CompileIntoHL(args[0]); EmitAsm("PUSH_HL"); // dst
                CompileIntoHL(args[1]); EmitAsm("PUSH_HL"); // src
                EmitAsm("LD_BC_IMM", new AsmOperand(copyLen, AddressMode.Immediate16));
                EmitAsm("POP_DE"); // src
                EmitAsm("POP_HL"); // dst
                EmitRamMemcpyLoop(funcName.TrimStart('_'));
                return;
            }

void EmitRamMemcpyLoop(string labelPrefix)
    {
        AsmOperand loop = MakeUniqueLabel(labelPrefix + "_loop");
        AsmOperand done = MakeUniqueLabel(labelPrefix + "_done");

        EmitLabel(loop);
        EmitAsm("LD_A_B");
        EmitAsm("OR_C");
        EmitAsm("JR_Z", done);
        EmitAsm("LD_A_DE");
        EmitAsm("LDI_HL_A");
        EmitAsm("INC_DE");
        EmitAsm("DEC_BC");
        EmitAsm("JR", loop);
        EmitLabel(done);
    }

// kitaqgb/kitaqgb/Lowerer.cs:2145
if (expr.MatchAny(Tag.Call, out callFunc, out callArgs))
        {
            string knownCallName;
            if (callFunc != null && callFunc.Match(Tag.Name, out knownCallName) &&
                knownCallName == "__cgb_is_cgb" &&
                callArgs != null && callArgs.Length == 0 &&
                // A resolved target configuration can replace the zero-argument CGB query with a literal.
                Program.TryGetKnownCgbRuntimeValue(out int knownCgbValue))
            {
                return Expr.Make(Tag.Integer, knownCgbValue).WithSource(expr.Source);
            }

            Expr newFunc = LowerExpr(ctx, callFunc, false, prefix);

            // Optimization (post-A3): when we must spill a non-atomic argument into a temp,
            // prefer a u8 temp if the *parameter type* is u8-like.
            // This preserves semantics (implicit truncation to u8) while avoiding needless
            // u16 temporaries created by integer promotions.
            CType[] paramTypes = null;
            string __fname = null;
            if (newFunc.Match(Tag.Name, out __fname))
            {
                paramTypes = ctx.FindFuncParams(__fname);
                if (paramTypes == null)
                {
                    CType fnTypeFromName;
                    if (TryGetCallableFunctionType(ctx.FindTypeOfName(__fname), out fnTypeFromName))
                        paramTypes = fnTypeFromName.ParamTypes;
                }
            }
            else
            {
                CType fnTypeFromExpr;
                if (TryGetCallableFunctionType(InferType(ctx, newFunc), out fnTypeFromExpr))
                    paramTypes = fnTypeFromExpr.ParamTypes;
            }

            Expr[] newArgs = new Expr[callArgs.Length];
            for (int i = 0; i < callArgs.Length; i++)
            {
                Expr a = LowerExpr(ctx, callArgs[i], allowExtract, prefix);
                bool preserveConstantArgIntrinsic = false;
                if (a.MatchAny(Tag.Call, out Expr argFunc, out Expr[] _argCallArgs) &&
                    argFunc.Match(Tag.Name, out string argFuncName))
                {
                    preserveConstantArgIntrinsic = (argFuncName == "__bankof" || argFuncName == "__cgb_is_cgb");
                }
                // Keep evaluable constants and special intrinsic/bank operands visible to code generation instead of spilling them.
                bool preserveCompileTimeConstantArg = ctx.Global.TryEvalConstInt(a, out _);
                bool preserveFarcallBankArg = (__fname == "__farcall" && i == 0);

                if (allowExtract && !preserveFarcallBankArg && !preserveConstantArgIntrinsic && !preserveCompileTimeConstantArg && !IsAtom(a))
                {
                    // If we know the callee's parameter type, use it to choose a smaller temp.
                    // Example: (u8)(row*32) passed to a u8 param should spill as u8, not u16.
                    CType spillAs = null;
                    if (paramTypes != null && i < paramTypes.Length)
                    {
                        CType pt = paramTypes[i];
                        if (IsU8Like(pt)) spillAs = CType.UInt8;
                    }
                    if (spillAs == null) spillAs = InferType(ctx, a);
                    if (!IsAggregateType(spillAs) && SizeOfType(spillAs) <= 2)
                        a = SpillToTemp(ctx, a, spillAs, prefix);
                }
                newArgs[i] = a;
            }

            // Lint: const discard for argument passing
            // Warn when passing a const-qualified pointer (or const array decay) to a non-const pointer parameter.
            // Suppress when the argument has an explicit cast, or inside __unsafe.
            if (!ctx.InUnsafe && paramTypes != null)
            {
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    CType pt = paramTypes[i];
                    if (pt == null) continue;
                    if (!IsPointerToNonConst(pt)) continue;
                    if (HasTopLevelCast(newArgs[i])) continue;

                    CType at = InferType(ctx, newArgs[i]);
                    if (at != null && (IsPointerToConst(at) || IsArrayOfConst(at)))
                    {
                        string fn = __fname ?? "<call>";
                        WarnConstDiscard(expr, $"argument {i} to '{fn}'");
                        break; // keep it quiet: one warning per call is enough
                    }
                }
            }

            if (paramTypes != null)
            {
                string fn = __fname ?? "<call>";
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    FilePosition argPos = newArgs[i].Source;
                    if (string.IsNullOrEmpty(argPos.Filename) || argPos.Filename == "<unknown>")
                        argPos = expr.Source;
                    WarnImplicitNarrowingIfNeeded(ctx, newArgs[i], InferType(ctx, newArgs[i]), paramTypes[i], argPos,
                        "argument " + i + " to '" + fn + "'");
                }
            }

            // Lint: __enum_strict argument passing.
            if (paramTypes != null)
            {
                string fn = __fname ?? "<call>";
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    CType pt = paramTypes[i];
                    if (pt == null) continue;

                    CType at = InferType(ctx, newArgs[i]);
                    if (at == null) continue;

                    if (HasTopLevelCast(newArgs[i])) continue;

                    if (IsStrictEnum(pt))
                    {
                        if (!IsSameEnum(pt, at))
                        {
                            Program.Warning(expr.Source, ErrorCode.EnumStrictMix,
                                "argument {0} to '{1}' expects __enum_strict {2}, got {3}; cast explicitly to silence",
                                i, fn, pt.Show(), at.Show());
                        }
                    }
                    else if (IsPlainInteger(pt) && IsStrictEnum(at))
                    {
                        Program.Warning(expr.Source, ErrorCode.EnumStrictMix,
                            "argument {0} to '{1}' passes __enum_strict {2} to integer parameter {3}; cast explicitly to silence",
                            i, fn, at.Show(), pt.Show());
                    }
                }
            }

            if (!ctx.InUnsafe)
                RestrictAliasLint(ctx, newFunc, newArgs, expr.Source);

            // __slice(ptr,len) helper: represent a "slice" (ptr+len) in the IR.
            // Semantics: evaluate both arguments, result type is the pointer/array (same as arg0).
            // Bounds checks are injected only with -Zcheck (see Program.CheckSliceBounds).
            // Note: keep the intrinsic name conservative to avoid collisions ("slice" is allowed only
            // when there is no declared function named "slice").
            if (newFunc.Match(Tag.Name, out string __sfname))
            {
                bool isSliceIntrinsic = (__sfname == "__slice") || (__sfname == "slice" && ctx.FindFuncParams("slice") == null);
                if (isSliceIntrinsic)
                {
                    if (newArgs.Length != 2)
                    {
                        Program.Error(expr.Source, ErrorCode.ParseError, "{0}: expected 2 arguments: __slice(ptr,len)", __sfname);
                    }
                    else
                    {
                        CType pty = InferType(ctx, newArgs[0]);
                        if (pty == null || !(pty.IsPointer || pty.IsArray))
                            Program.Error(expr.Source, ErrorCode.ExpectedType, "{0}: first argument must be a pointer or array, got: {1}", __sfname, (pty == null ? "<unknown>" : pty.Show()));

                        CType lty = InferType(ctx, newArgs[1]);
                        if (lty == null || !lty.IsInteger)
                            Program.Error(expr.Source, ErrorCode.ExpectedType, "{0}: second argument must be an integer length, got: {1}", __sfname, (lty == null ? "<unknown>" : lty.Show()));
                    }

                    return Expr.Make(Tag.Slice, newArgs[0], newArgs[1]).WithSource(expr.Source);
                }
            }

            return MakeCall(newFunc, newArgs).WithSource(expr.Source);
        }

Copy exactly 32 bytes from src to dst, with no length argument. Use it for a fixed 32-byte record or two adjacent 16-byte tile patterns in CPU-accessible memory. It performs a forward byte copy, not a single 32-bit load or a banked transfer.

Syntax

void __copy32(void* dst, const void* src);

Parameters

dst

Pointer to the first writable destination byte. Reserve enough consecutive bytes for the complete operation; no buffer is allocated for you.

src

Pointer to the first readable source byte. The entire range must remain accessible and unchanged throughout the copy.

Return value

None (void).

Conditions and limits

Use separate, non-overlapping source and destination ranges. These routines copy forward and do not provide overlap-safe memmove behavior; writing into the unread part of the source can corrupt later bytes.

The operation finishes before the caller continues. It neither switches ROM/RAM banks nor clips a range to a buffer boundary. Keep mappings stable, use valid memory ranges and coordinate access with interrupt handlers that use the same buffers.

On GB, these are ordinary CPU memory accesses. They do not wait for safe VRAM/OAM access, start DMA or select a CGB VRAM/WRAM bank. Use the dedicated graphics-transfer APIs for those jobs.

Usage example

memory_reset();
__copy32(memory_destination+1,memory_source+1);
memory_copy_32=memory_check(32,0);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This example uses __copy32 to copy 32 patterned bytes starting at offset 1. memory_check compares the entire source and destination arrays; the COPY32 row must show 032. Starting inside the buffer leaves a leading guard byte, and bytes after the payload must also remain unchanged.

The complete program resets two 264-byte buffers before each operation, then checks every source byte, every destination byte and the untouched guard regions. The expected rows are COPY WORD 257, FILL WORD 257, COPY BYTE 255, FILL BYTE 255, COPY16 016, COPY32 032, ZERO CALLS 002 and FAILED 000. WORD/BYTE describe the count width, not the size of each copied item. The numbers are produced by the sample's checks, not return values from these void functions.

The captured screens show black lettering on white for DMG, blue on white for CGB and blue on black for FC. This example verifies RAM operations; the lettering presents the results rather than demonstrating a drawing primitive. Separate emulator checks cover 88 memory cases on each platform, including constant and runtime lengths at 0, 1, 16, 17, 32, 33, 64, 65 and 255 bytes, plus 256 and 257 for the word-count forms. Physical hardware has not been tested.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\memory_intrinsics.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\memory_intrinsics.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

if (funcName == "__copy16" || funcName == "__copy32")
            {
                if (args.Length != 2) Error(expr, funcName + "(dst, src) expects 2 arguments");

                int copyLen = (funcName == "__copy16") ? 16 : 32;
                CompileIntoHL(args[0]); EmitAsm("PUSH_HL"); // dst
                CompileIntoHL(args[1]); EmitAsm("PUSH_HL"); // src
                EmitAsm("LD_BC_IMM", new AsmOperand(copyLen, AddressMode.Immediate16));
                EmitAsm("POP_DE"); // src
                EmitAsm("POP_HL"); // dst
                EmitRamMemcpyLoop(funcName.TrimStart('_'));
                return;
            }

void EmitRamMemcpyLoop(string labelPrefix)
    {
        AsmOperand loop = MakeUniqueLabel(labelPrefix + "_loop");
        AsmOperand done = MakeUniqueLabel(labelPrefix + "_done");

        EmitLabel(loop);
        EmitAsm("LD_A_B");
        EmitAsm("OR_C");
        EmitAsm("JR_Z", done);
        EmitAsm("LD_A_DE");
        EmitAsm("LDI_HL_A");
        EmitAsm("INC_DE");
        EmitAsm("DEC_BC");
        EmitAsm("JR", loop);
        EmitLabel(done);
    }

// kitaqgb/kitaqgb/Lowerer.cs:2145
if (expr.MatchAny(Tag.Call, out callFunc, out callArgs))
        {
            string knownCallName;
            if (callFunc != null && callFunc.Match(Tag.Name, out knownCallName) &&
                knownCallName == "__cgb_is_cgb" &&
                callArgs != null && callArgs.Length == 0 &&
                // A resolved target configuration can replace the zero-argument CGB query with a literal.
                Program.TryGetKnownCgbRuntimeValue(out int knownCgbValue))
            {
                return Expr.Make(Tag.Integer, knownCgbValue).WithSource(expr.Source);
            }

            Expr newFunc = LowerExpr(ctx, callFunc, false, prefix);

            // Optimization (post-A3): when we must spill a non-atomic argument into a temp,
            // prefer a u8 temp if the *parameter type* is u8-like.
            // This preserves semantics (implicit truncation to u8) while avoiding needless
            // u16 temporaries created by integer promotions.
            CType[] paramTypes = null;
            string __fname = null;
            if (newFunc.Match(Tag.Name, out __fname))
            {
                paramTypes = ctx.FindFuncParams(__fname);
                if (paramTypes == null)
                {
                    CType fnTypeFromName;
                    if (TryGetCallableFunctionType(ctx.FindTypeOfName(__fname), out fnTypeFromName))
                        paramTypes = fnTypeFromName.ParamTypes;
                }
            }
            else
            {
                CType fnTypeFromExpr;
                if (TryGetCallableFunctionType(InferType(ctx, newFunc), out fnTypeFromExpr))
                    paramTypes = fnTypeFromExpr.ParamTypes;
            }

            Expr[] newArgs = new Expr[callArgs.Length];
            for (int i = 0; i < callArgs.Length; i++)
            {
                Expr a = LowerExpr(ctx, callArgs[i], allowExtract, prefix);
                bool preserveConstantArgIntrinsic = false;
                if (a.MatchAny(Tag.Call, out Expr argFunc, out Expr[] _argCallArgs) &&
                    argFunc.Match(Tag.Name, out string argFuncName))
                {
                    preserveConstantArgIntrinsic = (argFuncName == "__bankof" || argFuncName == "__cgb_is_cgb");
                }
                // Keep evaluable constants and special intrinsic/bank operands visible to code generation instead of spilling them.
                bool preserveCompileTimeConstantArg = ctx.Global.TryEvalConstInt(a, out _);
                bool preserveFarcallBankArg = (__fname == "__farcall" && i == 0);

                if (allowExtract && !preserveFarcallBankArg && !preserveConstantArgIntrinsic && !preserveCompileTimeConstantArg && !IsAtom(a))
                {
                    // If we know the callee's parameter type, use it to choose a smaller temp.
                    // Example: (u8)(row*32) passed to a u8 param should spill as u8, not u16.
                    CType spillAs = null;
                    if (paramTypes != null && i < paramTypes.Length)
                    {
                        CType pt = paramTypes[i];
                        if (IsU8Like(pt)) spillAs = CType.UInt8;
                    }
                    if (spillAs == null) spillAs = InferType(ctx, a);
                    if (!IsAggregateType(spillAs) && SizeOfType(spillAs) <= 2)
                        a = SpillToTemp(ctx, a, spillAs, prefix);
                }
                newArgs[i] = a;
            }

            // Lint: const discard for argument passing
            // Warn when passing a const-qualified pointer (or const array decay) to a non-const pointer parameter.
            // Suppress when the argument has an explicit cast, or inside __unsafe.
            if (!ctx.InUnsafe && paramTypes != null)
            {
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    CType pt = paramTypes[i];
                    if (pt == null) continue;
                    if (!IsPointerToNonConst(pt)) continue;
                    if (HasTopLevelCast(newArgs[i])) continue;

                    CType at = InferType(ctx, newArgs[i]);
                    if (at != null && (IsPointerToConst(at) || IsArrayOfConst(at)))
                    {
                        string fn = __fname ?? "<call>";
                        WarnConstDiscard(expr, $"argument {i} to '{fn}'");
                        break; // keep it quiet: one warning per call is enough
                    }
                }
            }

            if (paramTypes != null)
            {
                string fn = __fname ?? "<call>";
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    FilePosition argPos = newArgs[i].Source;
                    if (string.IsNullOrEmpty(argPos.Filename) || argPos.Filename == "<unknown>")
                        argPos = expr.Source;
                    WarnImplicitNarrowingIfNeeded(ctx, newArgs[i], InferType(ctx, newArgs[i]), paramTypes[i], argPos,
                        "argument " + i + " to '" + fn + "'");
                }
            }

            // Lint: __enum_strict argument passing.
            if (paramTypes != null)
            {
                string fn = __fname ?? "<call>";
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    CType pt = paramTypes[i];
                    if (pt == null) continue;

                    CType at = InferType(ctx, newArgs[i]);
                    if (at == null) continue;

                    if (HasTopLevelCast(newArgs[i])) continue;

                    if (IsStrictEnum(pt))
                    {
                        if (!IsSameEnum(pt, at))
                        {
                            Program.Warning(expr.Source, ErrorCode.EnumStrictMix,
                                "argument {0} to '{1}' expects __enum_strict {2}, got {3}; cast explicitly to silence",
                                i, fn, pt.Show(), at.Show());
                        }
                    }
                    else if (IsPlainInteger(pt) && IsStrictEnum(at))
                    {
                        Program.Warning(expr.Source, ErrorCode.EnumStrictMix,
                            "argument {0} to '{1}' passes __enum_strict {2} to integer parameter {3}; cast explicitly to silence",
                            i, fn, at.Show(), pt.Show());
                    }
                }
            }

            if (!ctx.InUnsafe)
                RestrictAliasLint(ctx, newFunc, newArgs, expr.Source);

            // __slice(ptr,len) helper: represent a "slice" (ptr+len) in the IR.
            // Semantics: evaluate both arguments, result type is the pointer/array (same as arg0).
            // Bounds checks are injected only with -Zcheck (see Program.CheckSliceBounds).
            // Note: keep the intrinsic name conservative to avoid collisions ("slice" is allowed only
            // when there is no declared function named "slice").
            if (newFunc.Match(Tag.Name, out string __sfname))
            {
                bool isSliceIntrinsic = (__sfname == "__slice") || (__sfname == "slice" && ctx.FindFuncParams("slice") == null);
                if (isSliceIntrinsic)
                {
                    if (newArgs.Length != 2)
                    {
                        Program.Error(expr.Source, ErrorCode.ParseError, "{0}: expected 2 arguments: __slice(ptr,len)", __sfname);
                    }
                    else
                    {
                        CType pty = InferType(ctx, newArgs[0]);
                        if (pty == null || !(pty.IsPointer || pty.IsArray))
                            Program.Error(expr.Source, ErrorCode.ExpectedType, "{0}: first argument must be a pointer or array, got: {1}", __sfname, (pty == null ? "<unknown>" : pty.Show()));

                        CType lty = InferType(ctx, newArgs[1]);
                        if (lty == null || !lty.IsInteger)
                            Program.Error(expr.Source, ErrorCode.ExpectedType, "{0}: second argument must be an integer length, got: {1}", __sfname, (lty == null ? "<unknown>" : lty.Show()));
                    }

                    return Expr.Make(Tag.Slice, newArgs[0], newArgs[1]).WithSource(expr.Source);
                }
            }

            return MakeCall(newFunc, newArgs).WithSource(expr.Source);
        }

Temporarily select a ROM bank, copy len bytes from src to dst in increasing address order, then restore the compiler’s saved ROM bank. __farmemcpy and __far_memcpy use the same implementation on this platform.

Syntax

void __far_memcpy(void* dst, u8 bank, const void* src, u16 len);

Parameters

dst

Destination in writable memory. Reserve enough space for every byte copied. Except for a zero-byte transfer, a null or invalid destination is not checked.

bank

8-bit bank selector for the source ROM mapping. Use a bank supported by the cartridge and the compiler’s bank layout; this argument is separate from the source address.

src

Near pointer to readable source bytes in the selected ROM bank. It does not contain a bank number.

len

Byte count, 0–65535. Zero performs no memory copy, but the bank-selection and restoration steps still run.

Return value

None (void).

Conditions and limits

Keep the full source range in the intended ROM mapping and the full destination range in writable memory. Copying does not select the next bank at a window boundary, handle overlapping ranges like memmove, or provide VRAM-safe writes. Use the graphics transfer APIs for VRAM.

The samples place calling code in fixed bank 0 so source-bank changes cannot unmap the code being executed. These transfers are synchronous. Do not interrupt a transfer with another bank-changing copy or assume the helper makes a whole application interrupt-safe.

The GB helper restores the compiler’s ROM-bank shadow. Use __bankswitch to maintain it; raw writes to the mapper do not update that shadow. Its saved-bank slot in HRAM is shared, so nested transfers that overwrite it are unsafe.

Usage example

__far_memcpy(buffer,2,asset_shapes,32); // Same backend as __farmemcpy.
expect(*asset_bank_marker==0xA1,29);
for(i=0;i<32;i++) expect(buffer[(__safe_index u8)i]==expected_shape_byte(i),32);
buffer[32]=0x55;
__far_memcpy(buffer+32,2,asset_shapes,0); // Zero count writes no bytes and restores the bank.
expect(buffer[32]==0x55 && *asset_bank_marker==0xA1,30);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Copy two patterns, 32 bytes, from payload bank 2 while bank 1 is initially selected. The program compares every copied byte, checks that bank 1 is restored and verifies that a zero-length copy leaves a 0x55 sentinel unchanged.

Expected image: a red row starts at pixel (16,32) and spans 72×8 pixels. It repeats an 8×8 triangle, an 8×8 square outline with a one-pixel border, and a tile with its left four columns filled, three times. The triangle grows from one pixel at the top left to eight pixels on its bottom row.

On GB, a blue triangle and outline at (16,64) show the __farmemcpy result; a green pair at (16,96) shows __far_memcpy. Each pair occupies 16×8 pixels. CGB shows these colors; DMG shows the same shapes in black on white.

Expected status: FAILED CHECKS 000 and FIRST FAILURE 00. The verification runs 300 frames and compares text, shape masks and colors against these expectations. This is emulator evidence, not a physical-hardware test.

Complete example program

Build command