PPU.java

package com.rox.ppu;

import com.rox.ByteUtil;

import com.rox.cartridge.Cartridge;

import com.rox.cartridge.Mirroring;

import com.rox.clock.ClockWatcher;

import com.rox.mem.OamDmaBus;

import static com.rox.ByteUtil.*;

import static com.rox.ByteUtil.BYTE_MASK;

/**

 * Headless NES PPU: correct vblank/NMI timing, full {@code $0000-$3FFF} PPU address space wiring

 * (CHR pattern tables via the cartridge, mirrored nametable RAM, palette RAM), the "loopy" internal

 * scroll/address registers, OAM DMA, and background + sprite rendering to a {@link #framebuffer()} of

 * raw palette indices (0-63) - {@link #rgbFramebuffer()} converts those through {@link NesPalette} for

 * actual display. Registers repeat every 8 bytes through {@code $2000-$3FFF}.

 *

 * Runs at 3 dots per CPU cycle (NTSC), 341 dots/scanline, 262 scanlines/frame. Vblank starts at

 * scanline 241 dot 1 and clears at the start of the pre-render scanline (261, dot 1) - matching real

 * hardware, this happens automatically every frame regardless of whether {@code $2002} is ever read.

 * NMI is modeled as a real level (vblank flag AND the control register's NMI-enable bit) with edge

 * detection, not a one-shot check at vblank's start: this also reproduces the documented hardware

 * quirk where enabling NMI while the vblank flag is already set fires an NMI immediately. Callers

 * drive the CPU's actual NMI line from {@link #consumeNmiEdge()}, one-shot per rising edge (mirrors

 * {@code MOS6502}'s own {@code signalNMI()}/{@code consumeNMI()} edge-latch pattern) - see how

 * {@code NES.java} wires this in exactly like the existing APU-IRQ listener.

 *

 * The internal current/temporary VRAM address, fine-X-scroll and write-toggle fields follow nesdev's

 * standard "loopy" model (traditionally named {@code v}/{@code t}/{@code x}/{@code w} there):

 * {@link #currentVramAddress} (used for {@code $2007} access) and {@link #temporaryVramAddress}

 * (staged by {@code $2005}/{@code $2006} until latched into {@code currentVramAddress}) are both

 * conceptually 15 bits laid out as {@code 0yyy NNYY YYYX XXXX} (fine Y, nametable select, coarse Y,

 * coarse X); {@link #fineXScroll} is 3 bits; {@link #writeToggle} is shared by

 * {@code $2005}/{@code $2006}, reset by a {@code $2002} read. Besides the register-level bit

 * manipulation ({@code $2000} nametable-select bits, {@code $2005} coarse/fine split, {@code $2006}

 * address latching), {@code currentVramAddress} also drives the background rendering pipeline's own

 * rendering-time-only updates: coarse-X increment during fetches, Y increment at dot 256, and the

 * dot-257/280-304 horizontal/vertical copies from {@code temporaryVramAddress} - see

 * {@link #backgroundStep()}.

 *

 * Simplifications: no odd-frame dot skip (341*262 isn't evenly divisible by 3, so the exact CPU-cycle

 * offset of vblank drifts by fractions of a cycle frame to frame - harmless here, only the dot

 * position within a frame matters). Four-screen nametable mirroring isn't modeled (see

 * {@link Mirroring}). OAM DMA always stalls the CPU a fixed 514 cycles, not real hardware's 513 (even

 * start cycle) or 514 (odd) - no total-cycle counter exists anywhere in the CPU to detect that parity,

 * and the 1-cycle difference doesn't affect correctness, only real-hardware-exact timing.

 *

 * Sprite pipeline simplifications: real hardware spreads secondary-OAM evaluation and sprite pattern

 * fetching across dots 65-256 and 257-320 respectively; both are collapsed here into a single step (at

 * dots 65 and 257) since nothing outside the PPU can observe mid-evaluation/mid-fetch state - the

 * resulting secondary OAM and fetched pattern bytes are byte-for-byte identical to real hardware's by

 * the time the next scanline starts. <b>One documented exception</b>: {@link com.rox.cartridge.Mmc3Mapper}

 * treats every {@link com.rox.cartridge.Mapper#readChr} call as directly observable (it clocks its IRQ

 * counter off the PPU address bus's A12 line), so collapsing dots 257-320's per-slot fetches into one

 * dot-257 step is only timing-transparent to it when at most one A12 edge would occur across those real

 * dots anyway - true for the common case, not for 8x16 sprites mixing pattern-table halves across

 * sprites; see {@link com.rox.cartridge.Mmc3Mapper}'s own class doc "Known limitation" note. Sprite

 * overflow uses a simple "found more than 8 sprites in range"

 * count, not real hardware's well-known buggy diagonal-read overflow detection (see nesdev's "Sprite

 * overflow bug") - only the obscure false-positive/false-negative edge cases differ, not correct

 * rendering. OAMADDR's glitchy behaviour during evaluation (real hardware corrupts low OAM entries if

 * OAMADDR isn't 0 at the start of a scanline) isn't modeled.

 */

public class PPU implements ClockWatcher, OamDmaBus {

    public static final int FRAMEBUFFER_WIDTH = 256;

    public static final int FRAMEBUFFER_HEIGHT = 240;

    /**

     * Where things fall on the 341-dot/scanline, 262-scanline/frame grid: scanlines 0-239 are visible,

     * 240 is post-render (idle), 241-260 are vertical blank, 261 is the pre-render scanline.

     * {@code DOTS_PER_SCANLINE}/{@code SCANLINES_PER_FRAME} are public since the debug viewer's

     * {@code BeamPositionPanel} draws against them directly; everything else here is {@code PPU}-internal.

     */

    public static final class FrameTiming {

        public static final int DOTS_PER_SCANLINE = 341;

        public static final int SCANLINES_PER_FRAME = 262;

        static final int DOTS_PER_CPU_CYCLE = 3;

        static final int VBLANK_START_SCANLINE = 241;

        static final int VBLANK_END_SCANLINE = 261;

        static final int VBLANK_EDGE_DOT = 1;

        static final int VISIBLE_SCANLINE_MAX = 239;

        //341 dots/scanline isn't a multiple of the 3 dots/CPU-cycle rate, so the target dot doesn't

        //always land on a tick boundary - round up (ceiling division) to the tick whose 3-dot span

        //contains it. advanceDot() itself checks after every individual dot, not just per tick(), so

        //this only matters for computing these two "how many ticks until X" constants, not correctness.

        /** CPU ticks from power-on/reset until vblank first starts - exact, useful for tests. */

        /** CPU ticks from power-on/reset until vblank first clears (pre-render scanline). */

        private static int ceilingDivide(final int numerator, final int denominator){

        }

    }

    /** {@code $2000-$2007}'s CPU-bus offsets - registers repeat every 8 bytes through {@code $2000-$3FFF}. */

    private static final class RegisterAddress {

        static final int MASK = 0x07;

        static final int PPUCTRL = 0x00;

        static final int PPUMASK = 0x01;

        static final int PPUSTATUS = 0x02;

        static final int OAMADDR = 0x03;

        static final int OAMDATA = 0x04;

        static final int PPUSCROLL = 0x05;

        static final int PPUADDR = 0x06;

        static final int PPUDATA = 0x07;

    }

    private static final int VBLANK_STATUS_BIT = 0x80;

    private static final int OAM_SIZE = 0x100;

    private static final int OAM_ADDRESS_MASK = 0xFF;

    private static final int VRAM_ADDRESS_MASK = 0x3FFF;

    private static final int LOOPY_REGISTER_MASK = 0x7FFF;

    private static final int ADDRESS_HIGH_BYTE_SHIFT = 8;

    private static final int CHR_END_ADDRESS = 0x2000; //exclusive - $0000-$1FFF

    private static final int PALETTE_START_ADDRESS = 0x3F00; //inclusive - $3F00-$3FFF

    private static final int NAMETABLE_SIZE = 0x800; //2KB physical nametable RAM

    private static final int NAMETABLE_OFFSET_MASK = 0x3FF; //1KB per logical nametable

    private static final int NAMETABLE_TABLE_SHIFT = 10;

    private static final int NAMETABLE_TABLE_MASK = 0x03;

    private static final int PALETTE_SIZE = 0x20;

    private static final int PALETTE_INDEX_MASK = 0x1F;

    private static final int PALETTE_BACKDROP_MIRROR_BIT = 0x10;

    //t/v bit layout: 0yyy NNYY YYYX XXXX (fine Y | nametable select | coarse Y | coarse X)

    private static final int COARSE_X_MASK = 0x1F;

    private static final int COARSE_Y_SHIFT = 5;

    private static final int COARSE_Y_MASK = 0x1F;

    private static final int NAMETABLE_SELECT_SHIFT = 10;

    private static final int NAMETABLE_SELECT_MASK = 0x03;

    private static final int FINE_Y_SHIFT = 12;

    private static final int FINE_Y_MASK = 0x07;

    private static final int FINE_X_MASK = 0x07;

    private static final int COARSE_X_CLEAR_MASK = ~COARSE_X_MASK & LOOPY_REGISTER_MASK;

    private static final int COARSE_Y_CLEAR_MASK = ~(COARSE_Y_MASK << COARSE_Y_SHIFT) & LOOPY_REGISTER_MASK;

    private static final int NAMETABLE_SELECT_CLEAR_MASK = ~(NAMETABLE_SELECT_MASK << NAMETABLE_SELECT_SHIFT) & LOOPY_REGISTER_MASK;

    private static final int FINE_Y_CLEAR_MASK = ~(FINE_Y_MASK << FINE_Y_SHIFT) & LOOPY_REGISTER_MASK;

    private static final int ADDRESS_HIGH_BYTE_MASK = 0x3F;

    private static final int ADDRESS_HIGH_BYTE_CLEAR_MASK = 0x00FF;

    private static final int ADDRESS_LOW_BYTE_CLEAR_MASK = 0x7F00;

    private static final int OAM_DMA_STALL_CYCLES = 514;

    //background rendering pipeline (nesdev's standard 8-dot tile-fetch cycle + shift registers),

    //verified dot-for-dot against nesdev's PPU_scrolling/PPU_rendering/PPU_palettes wiki pages

    private static final int TILE_FETCH_GROUP_DOTS = 8;

    private static final int MAIN_FETCH_REGION_END_DOT = 256; //dots 1-256

    private static final int HORIZONTAL_COPY_DOT = 257;

    private static final int PREFETCH_REGION_START_DOT = 321;

    private static final int PREFETCH_REGION_END_DOT = 336; //dots 321-336: next scanline's first 2 tiles

    private static final int PREFETCH_RELOAD_DOT = 337; //reloads the 2nd prefetched tile's data

    private static final int VERTICAL_COPY_START_DOT = 280;

    private static final int VERTICAL_COPY_END_DOT = 304; //pre-render only, dots 280-304 inclusive

    private static final int TILE_BYTES = 16; //8-byte low bitplane + 8-byte high bitplane

    private static final int PATTERN_HIGH_PLANE_OFFSET = 8;

    private static final int SHIFT_REGISTER_MASK = 0xFFFF;

    private static final int SHIFT_REGISTER_LOW_BYTE_CLEAR_MASK = 0xFF00;

    private static final int PIXEL_MUX_MSB = 0x8000;

    private static final int NAMETABLE_BASE_ADDRESS = 0x2000;

    private static final int NAMETABLE_FETCH_ADDRESS_MASK = 0x0FFF;

    private static final int ATTRIBUTE_BASE_ADDRESS = 0x23C0;

    private static final int ATTRIBUTE_NAMETABLE_MASK = 0x0C00;

    private static final int ATTRIBUTE_COARSE_Y_SHIFT_IN_ADDRESS = 4;

    private static final int ATTRIBUTE_COARSE_Y_ADDRESS_MASK = 0x38;

    private static final int ATTRIBUTE_COARSE_X_SHIFT_IN_ADDRESS = 2;

    private static final int ATTRIBUTE_COARSE_X_ADDRESS_MASK = 0x07;

    private static final int ATTRIBUTE_QUADRANT_BIT = 0x02;

    private static final int ATTRIBUTE_GROUP_MASK = 0x03;

    private static final int COARSE_X_MAX = 31; //wraps to 0 + toggles the nametable-X bit

    private static final int NAMETABLE_X_TOGGLE_BIT = 1 << NAMETABLE_SELECT_SHIFT; //bit 10 = 0x0400

    private static final int NAMETABLE_Y_TOGGLE_BIT = 1 << (NAMETABLE_SELECT_SHIFT + 1); //bit 11 = 0x0800

    private static final int FINE_Y_FULL_MASK = FINE_Y_MASK << FINE_Y_SHIFT; //0x7000

    private static final int COARSE_Y_WRAP_WITH_TOGGLE = 29; //last real row of tiles

    private static final int COARSE_Y_WRAP_WITHOUT_TOGGLE = 31; //attribute-table rows, no nametable toggle

    private static final int HORIZONTAL_COPY_MASK = COARSE_X_MASK | NAMETABLE_X_TOGGLE_BIT; //0x041F

    private static final int VERTICAL_COPY_MASK = FINE_Y_FULL_MASK | NAMETABLE_Y_TOGGLE_BIT

            | (COARSE_Y_MASK << COARSE_Y_SHIFT); //0x7BE0

    private static final int PALETTE_COLOR_MASK = 0x3F; //6-bit NES master-palette index (0-63)

    //sprite rendering pipeline (nesdev's standard OAM evaluation + pattern fetch + priority mux) - see

    //the class javadoc's "Sprite pipeline simplifications" paragraph for how this collapses real

    //hardware's multi-dot evaluation/fetch windows into single steps.

    private static final int OAM_SPRITE_COUNT = 64;

    private static final int OAM_BYTES_PER_SPRITE = 4;

    private static final int MAX_SPRITES_PER_SCANLINE = 8;

    private static final int SPRITE_HEIGHT_SHORT = 8;

    private static final int SPRITE_HEIGHT_TALL = 16;

    private static final int SPRITE_EVALUATION_DOT = 65;

    private static final int TALL_SPRITE_PATTERN_TABLE_SIZE = 0x1000;

    private static final int SPRITE_PALETTE_MASK = 0x03;

    private static final int SPRITE_PRIORITY_BEHIND_BACKGROUND_BIT = 0x20;

    private static final int SPRITE_FLIP_HORIZONTAL_BIT = 0x40;

    private static final int SPRITE_FLIP_VERTICAL_BIT = 0x80;

    private static final int SPRITE_PALETTE_RAM_OFFSET = 0x10; //$3F10-$3F1F vs background's $3F00-$3F0F

    private static final int SPRITE_ZERO_HIT_EXCLUDED_X = 255; //real hardware never sets the hit flag here

    private static final int SPRITE_ZERO_HIT_STATUS_BIT = 0x40;

    private static final int SPRITE_OVERFLOW_STATUS_BIT = 0x20;

    //real hardware's secondary-OAM-clear phase (dots 1-64) fills every byte with $FF; an unused sprite

    //slot's dummy pattern fetch (see fetchSpritesForNextScanline()) reads this same tile index

    private static final int DUMMY_SPRITE_TILE_INDEX = 0xFF;

    private final Cartridge cartridge;

    /**  a unit of time in which we advance by exactly one pixel-column's worth of work, whether or not that pixel is currently visible on screen. */

    private int dot;

    /** 341 dots, 256 of which are visible pixels */

    private int scanline;

    private boolean vblankFlag;

    private boolean previousNmiLine;

    private boolean nmiEdgePending;

    private int oamAddress;

    private boolean writeToggle; //shared $2005/$2006 write toggle

    private int temporaryVramAddress; //staged by $2005/$2006 until latched into currentVramAddress

    private int currentVramAddress; //used for $2007 access

    private int fineXScroll; //3 bits

    private int readBuffer; //$2007's one-read-of-latency buffer for non-palette addresses

    private boolean oamDmaPending;

    /** One raw palette-RAM index (0-63) per pixel - {@link #rgbFramebuffer()} converts these to real colour. */

    private boolean frameReady;

    //two tiles' worth of pattern/attribute data, shifted left 1 bit per dot; fineXScroll selects

    //which bit each pixel is drawn from (see drawPixel())

    private int bgPatternShiftLow;

    private int bgPatternShiftHigh;

    private int bgAttributeShiftLow;

    private int bgAttributeShiftHigh;

    //latches for the tile currently being fetched (2 tiles ahead of what's being drawn), folded

    //into the shift registers' low byte by reloadShiftRegisters()

    private int nextTileId;

    private int nextTilePaletteGroup; //2 bits (0-3)

    private int nextPatternLowByte;

    private int nextPatternHighByte;

    //secondary OAM for the upcoming scanline (up to 8 sprites x 4 bytes), rebuilt every scanline by

    //evaluateSpritesForNextScanline()

    private int secondaryOamCount;

    private boolean spriteOverflow;

    private boolean spriteZeroHitFlag;

    //per-slot rendering state fetchSpritesForNextScanline() loaded for the *current* scanline's active

    //sprites - pattern bytes already have horizontal flip applied, so drawPixel() never needs to know

    //about flip at all

    private int activeSpriteCount;

    /** CPU-cycle clock: the PPU itself runs at 3x this rate (once per dot, 3 dots per CPU cycle). */

    @Override

    public void tick(){

        }

    private void advanceDot(){

            }

        }

        }

    /** True exactly once per frame (set at scanline 241 dot 1) - mirrors {@link #consumeNmiEdge()}'s one-shot pattern. */

    public boolean consumeFrameReady(){

        }

    }

    /**

     * Runs on every dot of every visible (0-239) and pre-render (261) scanline. A pixel is drawn on

     * every dot 1-256 of a visible scanline regardless of whether rendering is enabled (falling back to

     * the backdrop colour when it isn't); the fetch/shift/scroll machinery below that only runs when

     * rendering is enabled - real hardware freezes the v register entirely otherwise.

     *

     * <p>The shift registers shift one dot <em>later</em> than the fetch switch's own dot range in each

     * region - dots 2-257 (not 1-256) and 322-337 (not 321-336) - and that shift happens <em>before</em>

     * this dot's pixel is drawn, not after: dot 1 draws directly from whatever the previous scanline's

     * prefetch already left sitting in the registers, with no shift of its own first. Getting either of

     * those backwards (shifting on the same 1-256/321-336 range the fetch switch uses, or drawing before

     * shifting) is a real, easy-to-make off-by-one - it shows up as the whole background shifted one

     * pixel to the right - caught here by simulating the exact algorithm against known CHR/nametable

     * fixtures before trusting it, not just by re-reading nesdev's timing diagram more carefully.

     */

    private void backgroundStep(){

        }

                    || (dot > PREFETCH_REGION_START_DOT && dot <= PREFETCH_RELOAD_DOT);

            }

        }

        }

        }

        }

        }

        }

        }

        }

    /**

     * The repeating 8-dot tile fetch (NT byte, attribute byte, pattern low, pattern high, coarse-X

     * increment) - runs during both the main fetch region (dots 1-256) and the next scanline's 2-tile

     * prefetch region (dots 321-336). Reload is skipped on the very first dot of either region (dot 1,

     * dot 321): the previous group's data was already folded in by {@link #backgroundStep()}'s explicit

     * dot-257/dot-337 reloads, so reloading again here would stomp the shift registers' just-shifted low

     * byte with stale data instead of letting it drain into the high byte - verified against nesdev's own

     * reload-cadence documentation (ticks 9, 17, ..., 257) before trusting this by-construction reasoning.

     */

    private void fetchStep(){

            case 0 -> {

                }

            default -> { }

        }

    /** The attribute byte's 2x2 grid of 2-bit palette-group values, indexed by which quadrant coarse X/Y falls in. */

    private int fetchAttributePaletteGroup(){

                | (currentVramAddress & ATTRIBUTE_NAMETABLE_MASK)

                | ((currentVramAddress >> ATTRIBUTE_COARSE_Y_SHIFT_IN_ADDRESS) & ATTRIBUTE_COARSE_Y_ADDRESS_MASK)

                | ((currentVramAddress >> ATTRIBUTE_COARSE_X_SHIFT_IN_ADDRESS) & ATTRIBUTE_COARSE_X_ADDRESS_MASK);

    }

    private int fetchPatternByte(final int planeOffset){

    }

    /** Folds the latched tile's data into the shift registers' low byte - the high byte drains from the previous tile. */

    private void reloadShiftRegisters(){

        //the 2-bit palette group is constant for all 8 pixels of a tile, so it's broadcast across a

        //whole byte (all-1s or all-0s per bit) rather than genuinely tracking 8 individual bits - a

        //well-known, behaviourally-identical simplification of real hardware's 1-bit-latch design

    private void shiftBackgroundShiftRegisters(){

    /** nesdev's standard coarse-X increment: wraps at 31, toggling the horizontal nametable-select bit. */

    private void incrementCoarseX(){

        } else {

        }

    /**

     * nesdev's standard fine/coarse-Y increment (dot 256 only): fine Y wraps into coarse Y, which

     * itself wraps at 29 (the real last row of tiles, toggling the vertical nametable-select bit) - but

     * at 31 (a coarse Y a game deliberately set out of bounds, into the attribute table) wraps to 0

     * *without* toggling the nametable bit, since that out-of-bounds value was never really "on" the

     * next nametable to begin with.

     */

    private void incrementFineY(){

        }

        } else {

        }

    /** hori(v)=hori(t): copies coarse X + the horizontal nametable-select bit, dot 257 only. */

    private void copyHorizontalBits(){

                | (temporaryVramAddress & HORIZONTAL_COPY_MASK)) & LOOPY_REGISTER_MASK;

    /** vert(v)=vert(t): copies fine Y + coarse Y + the vertical nametable-select bit, pre-render dots 280-304. */

    private void copyVerticalBits(){

                | (temporaryVramAddress & VERTICAL_COPY_MASK)) & LOOPY_REGISTER_MASK;

    private boolean renderingEnabled(){

    }

    /**

     * Runs on every dot of every visible (0-239) and pre-render (261) scanline, mirroring

     * {@link #backgroundStep()}'s scanline range. Builds secondary OAM for the scanline about to start

     * at dot 65 (real hardware: dots 65-256) and fetches that scanline's sprite pattern bytes at dot 257

     * (real hardware: dots 257-320) - see the class javadoc's sprite-pipeline simplification note for why

     * collapsing each multi-dot window into a single dot is behaviourally identical.

     */

    private void spriteStep(){

        }

        }

        }

        }

    /**

     * Builds secondary OAM (up to 8 sprites) for the scanline about to start, scanning primary OAM in

     * index order so slot 0 of secondary OAM (if occupied) is always the highest-priority sprite in

     * range - OAM index 0 specifically is also tracked (via {@link #secondaryOamSpriteZeroSlot}) for

     * sprite-0-hit detection. Sets {@link #spriteOverflow} (sticky until the pre-render scanline clears

     * it) when more than 8 sprites are in range; see the class javadoc for why this doesn't reproduce

     * real hardware's buggy overflow detection.

     *

     * <p>OAM byte 0 stores the sprite's top scanline <em>minus one</em> (real hardware's documented

     * "Y position" quirk - see nesdev's {@code PPU_OAM} page) - a sprite with {@code Y=N} is visible on

     * scanlines {@code N+1..N+height}, never on scanline 0 no matter what {@code Y} is. That {@code -1}

     * is folded into {@code row} below, and falls out naturally for the pre-render scanline's target of

     * 0: {@code row} is then always negative, so no sprite is ever found in range - correctly matching

     * real hardware's own "sprites are never displayed on the first line" behaviour without needing a

     * separate check.

     */

    private void evaluateSpritesForNextScanline(){

            }

                }

            }

        }

        }

    /**

     * Fetches pattern-table bytes for every sprite {@link #evaluateSpritesForNextScanline()} just found,

     * for the scanline about to start. Handles 8x8 vs 8x16 sizing ({@code $2000} bit 5; for 8x16, the

     * tile index's own low bit selects the pattern table and its high bits pick which of the pair of

     * tiles) and vertical/horizontal flip - horizontal flip is resolved here, once, by reversing the

     * fetched byte's bit order, rather than being checked per pixel at draw time.

     */

    private void fetchSpritesForNextScanline(){

            }

            final int patternTableBase;

            final int patternTileIndex;

                } else {

                }

            }

            }

        }

        //real hardware always fetches all 8 sprite slots every scanline - unused slots (secondary OAM

        //left at its $FF clear value) still perform a "dummy" tile-$FF fetch, discarded here since

        //activeSpriteCount below excludes them from rendering. Skipping these dummy reads entirely (as

        //this loop used to) is invisible to on-screen NROM/MMC1 output, but MMC3 games rely on exactly

        //these reads for their once-per-scanline A12 toggle (via Mmc3Mapper.readChr()) whenever a

        //scanline has fewer than 8 real sprites - the common case - so omitting them starves the MMC3

        //IRQ counter of the edges it needs.

        }

    /** Reverses an 8-bit value's bit order - implements horizontal sprite flip on a fetched pattern byte. */

    private static int reverseBits(final int value){

        }

    }

    /**

     * Resolves one framebuffer pixel by compositing the background shift-register state (selected by

     * {@link #fineXScroll}, as in Phase 3/4) with up to 8 active sprites for this scanline, in OAM-index

     * priority order - the first opaque sprite found wins, both for the final colour (subject to that

     * sprite's own front/back priority bit against an opaque background pixel) and for sprite-0-hit

     * detection, since OAM index 0 (if in range) is always secondary-OAM slot 0. Falls back to the

     * backdrop colour ({@code $3F00}) when nothing is opaque - real hardware's "universal background

     * colour" quirk, same as background-only rendering already relied on.

     */

    private void drawPixel(final int x, final int y){

            }

        }

                }

                }

                }

                            + (paletteGroup << 2) + spritePixelValue);

                break; //OAM-index priority: the first opaque sprite found wins, both for colour and hit detection

            }

        }

    private void setVblankFlag(final boolean asserted){

    /** NMI is a level (vblank && enabled) with edge detection, not a one-shot check at vblank start. */

    private void updateNmiLine(){

        }

    /** True exactly once per vblank/NMI-enable rising edge - the caller drives cpu.signalNMI() from this. */

    public boolean consumeNmiEdge(){

        }

    }

    @Override

    public int read(final int address){

        };

    }

    @Override

    public void write(final int address, final int value){

            default -> { }

        }

    /**

     * Handle a $2000 write - see {@link PPUControlRegister} for the full bit layout. Bit-level decoding

     * lives there; this method's own remaining concern is the nametable-select bits' side effect on the

     * loopy {@code t} register (latched into its nametable-select bits, 10-11) - takes effect the next

     * time {@code v} is reloaded from {@code t} (a $2006 second write, or the rendering pipeline's own

     * horizontal/vertical copies) - and re-checking the NMI line, since bit 7 can change it.

     */

    private void writeControlRegister(final int value){

    /**

     * Handle a $2002 read: vblank flag in bit 7, sprite-0-hit in bit 6, sprite overflow in bit 5.

     * Clears the vblank flag and resets the write-latch shared by $2005/$2006 - sprite-0-hit and

     * overflow are *not* cleared by this read, only by the pre-render scanline's dot 1 (see

     * {@link #advanceDot()}), matching real hardware.

     *

     * Deliberately does *not* call {@link #updateNmiLine()}: doing so here can only ever matter on a

     * falling transition (this read only ever clears vblankFlag, never sets it), which never sets

     * {@code nmiEdgePending} - and the pre-render scanline's own {@link #setVblankFlag(boolean)} call

     * always runs again before any later rising edge is possible, correctly resyncing

     * {@code previousNmiLine} by then regardless. Confirmed by simulation, not just by inspection.

     */

    private int readStatusRegister(){