; Mode7 rotozoomer: IE32 guest code submits an affine texture map to the IE blitter.
;
; The frame path derives signed fixed-point origin and step vectors, renders into a
; back buffer, then presents after the submission has completed.
; Read data layout, initialisation, per-frame vectors, blitter submission and table
; generation in order. Compare the other ports only for real CPU addressing changes.
;


.include "ie32.inc"

; ============================================================================
; CONSTANTS
; ============================================================================

; --- Texture Memory Layout ---
;
; The texture is a 256x256 pixel checkerboard placed at 0x600000, which is
; above VRAM (0x100000-0x2E0000 for 640x480x4). We use a stride of 1024
; bytes (256 pixels * 4 bytes/pixel) so that each row is contiguous.
;
; The checkerboard is built from four 128x128 quadrants using BLIT FILL:
;
;   +---+---+
;   | W | B |   W = white (0xFFFFFFFF)   B = black (0xFF000000)
;   +---+---+   Each quadrant is 128x128 pixels
;   | B | W |   Stride = 1024 bytes per row (256 * 4)
;   +---+---+
;
; The quadrant addresses are computed from TEXTURE_BASE + column offset
; and TEXTURE_BASE + row offset:
;   Top-left  = 0x600000                (row 0, col 0)
;   Top-right = 0x600200                (row 0, col 128 * 4 = +0x200)
;   Bot-left  = 0x620000                (row 128 * 1024 = +0x20000)
;   Bot-right = 0x620200                (row 128 * 1024 + col 128 * 4)
;
; 0x600000? This address is safely above the front buffer VRAM
; (0x100000 + 640*480*4 = ~0x2E0000) and below the back buffer (0x900000).
; Placing the texture in this gap means all three memory regions (front
; buffer, texture, back buffer) are non-overlapping and can be accessed
; simultaneously by the blitter without conflicts.
;
; STRIDE 1024? The texture is 256 pixels wide at 4 bytes/pixel =
; 1024 bytes per row. The blitter needs this stride to know how to
; advance from one row to the next in the texture source during Mode7
; rendering. The Mode7 mask (255) wraps texture coordinates to 0-255,
; creating the infinite-tiling illusion as the texture rotates.
.equ TEXTURE_BASE   0x600000
.equ TEX_TR         0x600200
.equ TEX_BL         0x620000
.equ TEX_BR         0x620200
.equ BACK_BUFFER_A  0x900000
.equ BACK_BUFFER_B  0xB00000
.equ RENDER_W       640
.equ RENDER_H       480
.equ TEX_STRIDE     1024
.equ LINE_BYTES_V   2560

; --- Animation Accumulator Increments (8.8 Fixed-Point) ---
;
; Animation uses 16-bit 8.8 fixed-point accumulators that wrap at 0xFFFF.
; The upper 8 bits index into the 256-entry sine/reciprocal tables, while
; the lower 8 bits provide sub-index fractional precision for smooth motion.
;
; ANGLE_INC=313 and SCALE_INC=104 maintain a 3:1 ratio, matching the
; original BASIC rotozoomer's `A+=0.03, SI+=0.01`. In 8.8 fixed-point:
;   0.03 * (256 / 2*pi) * 256 ~= 313
;   0.01 * (256 / 2*pi) * 256 ~= 104
;
; zoom cycle, creating a visually interesting Lissajous-like pattern where
; the same combination of angle+zoom never exactly repeats for a long time.
;
; 8.8 AND NOT PLAIN INTEGERS?
; If we incremented the table index directly by 1 each frame, the rotation
; would complete 256/60 ~ 4.3 seconds per revolution, which is too fast.
; Using 8.8 with an increment of 313 means the index advances by ~1.22
; per frame (313/256), giving ~3.5 seconds per revolution -- a more
; visually pleasing speed. The fractional accumulation also means the
; effective table index changes smoothly rather than in integer jumps.
.equ ANGLE_INC      313
.equ SCALE_INC      104

; --- Variable Addresses ---
;
; 0x46C20? The IE32 program starts at .org 0x1000 and can grow large
; (code + sine table + reciprocal table + AHX music data). Variables are
; placed at 0x46C20 to guarantee they don't overlap with any of the
; program's code or data sections. This address is in the gap between the
; program area and VRAM (which starts at 0x100000), providing ample room.
;
; Each variable is 4 bytes (32-bit), totaling 24 bytes for the 6 runtime
; state variables that drive the animation:
;
;   ANGLE_ACC  -- 8.8 FP accumulator for rotation angle
;   SCALE_ACC  -- 8.8 FP accumulator for zoom oscillation
;   CA         -- cos(angle) * recip(scale), the scaled cosine
;   SA         -- sin(angle) * recip(scale), the scaled sine
;   U0         -- starting texture U coordinate (16.16 FP)
;   V0         -- starting texture V coordinate (16.16 FP)
.equ VAR_BASE       0x46C20
.equ VAR_ANGLE_ACC  0x46C20
.equ VAR_SCALE_ACC  0x46C24
.equ VAR_CA         0x46C28
.equ VAR_SA         0x46C2C
.equ VAR_U0         0x46C30
.equ VAR_V0         0x46C34
.equ VAR_DRAW_FB    0x46C38

; ============================================================================
; PROGRAM ENTRY POINT
; ============================================================================
; The IE32 CPU begins execution at .org 0x1000 after loading the binary.
; We must initialise video, generate the texture, set up animation state,
; and start music before entering the main loop.
; ============================================================================

.org 0x1000

start:
    ; --- Enable VideoChip ---
    ; The VideoChip is the IE custom video system (distinct from VGA/ULA/etc).
    ; Mode 0 = 640x480 truecolour (32-bit BGRA). The blitter and VRAM are
    ; part of this subsystem, so it MUST be enabled before any blit operations.
    ; VIDEO_CTRL=1 enables the chip; VIDEO_MODE=0 selects Mode 0.
    LDA #1
    STA @VIDEO_CTRL
    LDA #0
    STA @VIDEO_MODE
    LDA #VRAM_START
    STA @VIDEO_FB_BASE

    ; --- Load Texture ---
    ; Copy the 256x256 RGBA texture (embedded via .incbin) to TEXTURE_BASE
    ; using a hardware BLIT COPY. The texture is pre-converted from
    ; rotozoomtexture.png.
    JSR load_texture

    ; --- Initialise Animation State ---
    ; Both accumulators start at zero. The angle accumulator determines
    ; rotation; the scale accumulator determines zoom oscillation.
    ; Starting both at zero means the demo begins with no rotation and
    ; the zoom at the midpoint of its oscillation range.
    LDA #0
    STA @VAR_ANGLE_ACC
    STA @VAR_SCALE_ACC
    LDA #BACK_BUFFER_A
    STA @VAR_DRAW_FB

    ; --- Start AHX Music Playback ---
    ; AHX (Abyss' Highest eXperience) is an Amiga-heritage tracker format.
    ; The audio subsystem handles playback entirely in the background --
    ; once started, it requires zero CPU involvement per frame.
    ;
    ; Setup: point the player at the embedded AHX data and tell it the size.
    ; The size is computed as (end label - start label) at assemble time.
    ;
    ; AHX_PLAY_CTRL = 5 = bit 0 (start) | bit 2 (loop).
    ; Looping ensures the music repeats seamlessly when it reaches the end,
    ; which is essential for a demo that runs indefinitely.
    LDA #ahx_data
    STA @AHX_PLAY_PTR
    LDA #ahx_data_end
    LDB #ahx_data
    SUB A, B
    STA @AHX_PLAY_LEN
    LDA #5
    STA @AHX_PLAY_CTRL

; ============================================================================
; MAIN LOOP
; ============================================================================
; Runs once per frame (~60 FPS with vsync). The order of operations is:
;
; 1. compute_frame:      Calculate the 6 Mode7 affine parameters from the
;                        current angle and scale accumulators.
; 2. render_mode7:       Program the blitter with those parameters and
;                        trigger a full-screen affine warp into the back
;                        buffer at 0x900000.
; 3. wait_vsync:         Synchronise with the vertical blank to prevent
;                        a completed buffer.
; 4. present_frame:      Point the VideoChip at the completed render buffer.
; 5. swap_draw_buffer:   Select the other render buffer for the next frame.
; 6. advance_animation:  Increment the angle and scale accumulators for
;                        the next frame.
;
; THIS ORDER?
; We compute and render before waiting for vsync. This means all the
; heavy work happens during the active display period (while the previous
; frame is being shown). The vblank edge then presents the completed buffer
; by updating VIDEO_FB_BASE.
; ============================================================================
main_loop:
    JSR compute_frame
    JSR render_mode7
    JSR wait_vsync
    JSR present_frame
    JSR swap_draw_buffer
    JSR advance_animation
    JMP main_loop

; ============================================================================
; WAIT FOR VSYNC (Two-Phase Synchronisation)
; ============================================================================
; Ensures exactly one frame passes between iterations of the main loop.
;
; TWO PHASES?
; A single "wait for vblank" is ambiguous -- if we're already IN vblank
; when we check, we'd return immediately and potentially run multiple
; frames within the same vblank period. The two-phase approach:
;
;   Phase 1 (wait_end):   Spin while vblank is ACTIVE. This drains any
;                         remaining vblank time from the previous frame.
;   Phase 2 (wait_start): Spin until vblank BEGINS. This catches the
;                         rising edge of the next vblank.
;
; Together, these guarantee we synchronise to exactly one vblank boundary
; per main-loop iteration after the vblank edge.
;
; STATUS_VBLANK is bit 1 (value 2) of the VIDEO_STATUS register.
; ============================================================================
wait_vsync:
wait_end:
    LDA @VIDEO_STATUS
    AND A, #STATUS_VBLANK
    JNZ A, wait_end
wait_start:
    LDA @VIDEO_STATUS
    AND A, #STATUS_VBLANK
    JZ A, wait_start
    RTS

; ============================================================================
; LOAD TEXTURE (256x256 RGBA from Embedded Raw Data via BLIT COPY)
; ============================================================================
; Copies the 256x256 RGBA texture from embedded raw data (texture_data,
; included via .incbin) to TEXTURE_BASE using a single hardware BLIT COPY.
; ============================================================================
load_texture:
    LDA #BLT_OP_COPY
    STA @BLT_OP
    LDA #texture_data
    STA @BLT_SRC
    LDA #TEXTURE_BASE
    STA @BLT_DST
    LDA #256
    STA @BLT_WIDTH
    STA @BLT_HEIGHT
    LDA #TEX_STRIDE
    STA @BLT_SRC_STRIDE
    STA @BLT_DST_STRIDE
    LDA #1
    STA @BLT_CTRL
lt_w1:
    LDA @BLT_CTRL
    AND A, #2
    JNZ A, lt_w1

    RTS

; ============================================================================
; COMPUTE FRAME - Calculate Mode7 Parameters from Animation State
; ============================================================================
; This is the mathematical heart of the rotozoomer. From two animation
; accumulators (angle and scale), we derive the 6 parameters the Mode7
; blitter needs: u0, v0, du_col, dv_col, du_row, dv_row.
;
; === ALGORITHM ===
;
; 1. Extract table indices from the 8.8 accumulators:
;      angle_idx = (angle_accum >> 8) & 255
;      scale_idx = (scale_accum >> 8) & 255
;
; 2. Look up trigonometric values from the sine table:
;      cos_val = sine_table[(angle_idx + 64) & 255]   (cosine = sine + 90 degrees)
;      sin_val = sine_table[angle_idx]
;
; 3. Look up zoom factor from the reciprocal table:
;      recip = recip_table[scale_idx]
;
; 4. Compute scaled cosine/sine (these ARE the column deltas):
;      CA = cos_val * recip   (signed multiply)
;      SA = sin_val * recip   (signed multiply)
;
; 5. Compute starting UV coordinates (16.16 fixed-point):
;      u0 = 8388608 - CA*320 + SA*240
;      v0 = 8388608 - SA*320 - CA*240
;
;    WHERE 8388608 = 128 << 16 = centre of a 256-pixel texture in 16.16 FP.
;    The CA*320 and SA*240 terms are half-screen offsets (640/2 and 480/2)
;    that shift the rotation pivot to the screen centre.
;
; === REGISTER ALLOCATION ===
; We use IE32's rich register set to avoid stack pressure:
;   D = angle_idx        E = scale_idx
;   F = cos_val          G = sin_val
;   H = recip            S = CA (scaled cosine)
;   T = SA (scaled sine) U = scratch for intermediate results
;   A, B, C = scratch (used extensively by multiply helpers)
;
; === PROPER SINE TABLES ===
; The values are computed as round(sin(i * 2*pi / 256) * 256), giving
; true circular rotation. A cheap approximation like a triangle wave
; would produce ~29% error at 45 degrees, causing visible distortion
; (the rotation would appear to "speed up" and "slow down" within each
; quadrant). With 256 entries, we get ~1.4 degree resolution, which is
; imperceptible at 60 FPS animation speed.
;
; === RECIPROCAL TABLE ===
; The reciprocal table provides zoom modulation:
;   recip[i] = round(256 / (0.5 + sin(i * 2*pi / 256) * 0.3))
;
; The 0.5 baseline ensures the zoom factor is always positive (no
; inversion). The 0.3 amplitude gives smooth oscillation between
; zoom levels ~320 (zoomed in) and ~1280 (zoomed out). Pre-computing
; avoids per-frame division, which IE32 lacks entirely (no DIV instruction).
; ============================================================================
compute_frame:
    ; --- Extract angle table index ---
    ; The accumulator is 8.8 fixed-point. Shifting right by 8 extracts
    ; the integer part, which directly indexes the 256-entry sine table.
    ; The AND #255 wraps the index, though it should already be in range
    ; since the accumulator is masked to 16 bits in advance_animation.
    LDA @VAR_ANGLE_ACC
    SHR A, #8
    AND A, #255
    LDD A                ; D = angle_idx (preserved across subroutine calls)

    ; --- Extract scale table index ---
    ; Same extraction for the scale accumulator. This index drives the
    ; reciprocal table, which controls the zoom oscillation.
    LDA @VAR_SCALE_ACC
    SHR A, #8
    AND A, #255
    LDE A                ; E = scale_idx

    ; --- Look up cos(angle) ---
    ; Cosine is sine phase-shifted by 90 degrees. In our 256-unit angle
    ; system, 90 degrees = 64 units (256/4). We add 64 to the angle index
    ; and wrap with AND #255 to get the cosine.
    ;
    ; SHL #2? IE32's .word directive emits 32-bit values, so each
    ; table entry is 4 bytes. Multiplying the index by 4 converts it to
    ; a byte offset for the table lookup.
    LDA D
    ADD A, #64
    AND A, #255
    SHL A, #2            ; *4 for 32-bit entries
    ADD A, #sine_table
    LDA [A]              ; A = cos_val (signed, already sign-extended in table)
    LDF A                ; F = cos_val

    ; --- Look up sin(angle) ---
    ; Direct table lookup using the angle index.
    LDA D
    SHL A, #2
    ADD A, #sine_table
    LDA [A]
    LDG A                ; G = sin_val

    ; --- Look up reciprocal (zoom factor) ---
    ; The reciprocal table is indexed by scale_idx. Values are unsigned
    ; (always positive) and range from 320 to 1280.
    LDA E
    SHL A, #2
    ADD A, #recip_table
    LDA [A]
    LDH A                ; H = recip (unsigned)

    ; --- Compute CA = cos_val * recip ---
    ; This is a signed * unsigned multiply. The sine values range -256 to
    ; +256 (signed), while the reciprocal is always positive (unsigned).
    ; We use the signed_mul helper which handles sign-magnitude conversion.
    ; CA is the per-column texture U delta and also used in the row delta.
    LDA F
    LDB H
    JSR signed_mul       ; A = CA
    STA @VAR_CA
    LDS A                ; S = CA (preserved for u0/v0 computation)

    ; --- Compute SA = sin_val * recip ---
    ; Same signed multiply for the sine component.
    ; SA is the per-column texture V delta and (negated) the row U delta.
    LDA G
    LDB H
    JSR signed_mul       ; A = SA
    STA @VAR_SA
    LDT A                ; T = SA

    ; --- Compute u0 = 8388608 - CA*320 + SA*240 ---
    ;
    ; 8388608?
    ; 8388608 = 128 << 16 = 0x800000. This is the centre of the 256-pixel
    ; texture in 16.16 fixed-point representation. The texture coordinates
    ; wrap at 255 (the Mode7 mask), so 128.0 in 16.16 FP places the
    ; origin at the texture centre.
    ;
    ; -CA*320 + SA*240?
    ; The screen is 640x480. Half-width = 320, half-height = 240.
    ; These terms offset from the texture centre by the rotated half-screen
    ; dimensions, ensuring the rotation pivots around the screen centre
    ; rather than the top-left corner. Without this centreing, the
    ; texture would rotate around pixel (0,0) and most of the visible
    ; area would show off-centre content.
    ;
    ; The formula comes from evaluating the affine transformation at the
    ; screen centre (320, 240) and solving for the origin:
    ;   u(320,240) should map to texture centre (128.0)
    ;   u0 = 128.0 - du_col*320 - du_row*240
    ;   u0 = 128.0 - CA*320 - (-SA)*240
    ;   u0 = 128.0 - CA*320 + SA*240
    LDA S
    JSR mul_320           ; A = CA*320
    LDU A                ; U = CA*320
    LDA T
    JSR mul_240           ; A = SA*240
    LDB #0x800000
    SUB B, U             ; B = 0x800000 - CA*320
    ADD B, A             ; B += SA*240
    STB @VAR_U0

    ; --- Compute v0 = 8388608 - SA*320 - CA*240 ---
    ;
    ; Same centreing logic for the V coordinate:
    ;   v(320,240) should map to texture centre (128.0)
    ;   v0 = 128.0 - dv_col*320 - dv_row*240
    ;   v0 = 128.0 - SA*320 - CA*240
    LDA T
    JSR mul_320           ; A = SA*320
    LDU A                ; U = SA*320
    LDA S
    JSR mul_240           ; A = CA*240
    LDB #0x800000
    SUB B, U             ; B = 0x800000 - SA*320
    SUB B, A             ; B -= CA*240
    STB @VAR_V0

    RTS

; ============================================================================
; SIGNED MULTIPLY: A = A * B (signed result)
; ============================================================================
; IE32-SPECIFIC: THIS EXISTS
;
; The IE32 CPU's MUL instruction is UNSIGNED only. It treats both operands
; as unsigned 32-bit integers. But our sine table contains signed values
; (-256 to +256), so we need signed multiplication for the core math.
;
; This subroutine implements the classic "sign-magnitude multiply" pattern
; used on CPUs without IMUL (like early MIPS and some microcontrollers):
;
;   1. Track the result sign: XOR of input signs
;      (positive*positive=positive, positive*negative=negative, etc.)
;   2. Take absolute values of both operands
;   3. Perform unsigned multiply
;   4. If result should be negative, negate it
;
; IE32-SPECIFIC: XOR/ADD FOR NEGATE
; IE32 has no NEG instruction. We use the two's complement identity:
;   -x = ~x + 1
; Implemented as:
;   XOR A, #0xFFFFFFFF    ; bitwise NOT (flip all bits)
;   ADD A, #1             ; add one
; This is the standard two's complement negate, equivalent to NEG on CPUs
; that have it. The XOR flips all bits (one's complement), and the +1
; converts from one's complement to two's complement.
;
; REGISTER USAGE:
;   Input:  A = first operand (signed), B = second operand (signed)
;   Output: A = A * B (signed result)
;   Clobbers: A, B, C (C is saved/restored via PUSH/POP)
;
; JGE A, label -- tests the int32 sign bit. If A >= 0 (sign bit clear),
; the operand is already positive and needs no negation.
; ============================================================================
signed_mul:
    PUSH C
    LDC #0               ; C = sign flag (0=positive result, 1=negative result)

    ; --- Check sign of A ---
    ; If A is negative (int32 < 0), negate it and toggle the sign flag.
    JGE A, sm_a_pos
    XOR A, #0xFFFFFFFF
    ADD A, #1            ; A = -A (two's complement negate)
    XOR C, #1            ; Toggle sign flag
sm_a_pos:
    ; --- Check sign of B ---
    ; Same treatment for the second operand.
    JGE B, sm_b_pos
    XOR B, #0xFFFFFFFF
    ADD B, #1
    XOR C, #1            ; Toggle again (two negatives make positive)
sm_b_pos:
    MUL A, B             ; Unsigned multiply of absolute values
    ; --- Conditionally negate result ---
    ; If the sign flag is set (operands had different signs), the result
    ; should be negative. Apply two's complement negate.
    JZ C, sm_done
    XOR A, #0xFFFFFFFF
    ADD A, #1
sm_done:
    POP C
    RTS

; ============================================================================
; MUL_320: A = A * 320 (signed) using shift decomposition
; ============================================================================
; IE32-SPECIFIC: SHIFT DECOMPOSITION WITH SIGN HANDLING
;
; Multiplying by 320 using MUL would work, but shift decomposition is a
; common optimization that avoids the multiply unit:
;   320 = 256 + 64 = (1 << 8) + (1 << 6)
; So: A * 320 = (A << 8) + (A << 6)
;
; HOWEVER, left shifts on IE32 are unsigned operations -- they don't
; preserve the sign bit in a meaningful way for signed arithmetic. Since
; CA and SA can be negative (signed 16.16 fixed-point values from the
; Mode7 matrix), we must:
;   1. Save the sign of the input
;   2. Take the absolute value
;   3. Perform the unsigned shift-and-add
;   4. Restore the original sign
;
; This is the same negate-before/negate-after pattern as signed_mul,
; applied to shift operations instead of MUL.
;
; REGISTER USAGE:
;   Input:  A = signed value to multiply by 320
;   Output: A = A * 320 (signed)
;   Clobbers: A, B, C (B and C are saved/restored)
; ============================================================================
mul_320:
    PUSH B
    PUSH C
    LDC #0               ; C = sign flag
    JGE A, m320_pos
    XOR A, #0xFFFFFFFF
    ADD A, #1            ; Negate to get absolute value
    LDC #1               ; Remember that result needs negation
m320_pos:
    LDB A               ; B = |A| (copy for the second shift)
    SHL A, #8            ; A = |A| * 256
    SHL B, #6            ; B = |A| * 64
    ADD A, B             ; A = |A| * 320
    JZ C, m320_done      ; If input was positive, we're done
    XOR A, #0xFFFFFFFF
    ADD A, #1            ; Negate back to restore sign
m320_done:
    POP C
    POP B
    RTS

; ============================================================================
; MUL_240: A = A * 240 (signed) using shift decomposition
; ============================================================================
; Same pattern as mul_320 but with different shift decomposition:
;   240 = 256 - 16 = (1 << 8) - (1 << 4)
; So: A * 240 = (A << 8) - (A << 4)
;
; Note the SUBTRACTION here (unlike mul_320's addition). This is because
; 240 = 256 - 16, not 256 + anything. The shift decomposition exploits
; the fact that 240 is close to a power of 2, making it expressible as
; a difference of two powers.
;
; REGISTER USAGE:
;   Input:  A = signed value to multiply by 240
;   Output: A = A * 240 (signed)
;   Clobbers: A, B, C (B and C are saved/restored)
; ============================================================================
mul_240:
    PUSH B
    PUSH C
    LDC #0
    JGE A, m240_pos
    XOR A, #0xFFFFFFFF
    ADD A, #1
    LDC #1
m240_pos:
    LDB A
    SHL A, #8            ; A = |A| * 256
    SHL B, #4            ; B = |A| * 16
    SUB A, B             ; A = |A| * (256 - 16) = |A| * 240
    JZ C, m240_done
    XOR A, #0xFFFFFFFF
    ADD A, #1
m240_done:
    POP C
    POP B
    RTS

; ============================================================================
; RENDER MODE7 - Configure and Trigger the Mode7 Affine Texture Blit
; ============================================================================
; Programs the hardware blitter with all parameters for a full-screen
; affine texture warp, then triggers the blit and waits for completion.
;
; DOUBLE BUFFERING?
; The Mode7 blit writes to the current off-screen render buffer, not the
; buffer currently being scanned out. At vblank, VIDEO_FB_BASE is updated
; to present the completed frame, then the other render buffer is selected.
;
; === BLITTER PARAMETER SETUP ===
;
;   BLT_OP = 5                    Mode7 affine texture mapping operation
;   BLT_SRC = TEXTURE_BASE        Source texture at 0x600000
;   BLT_DST = VAR_DRAW_FB         Current off-screen render buffer
;   BLT_WIDTH = 640               Output width in pixels
;   BLT_HEIGHT = 480              Output height in pixels
;   BLT_SRC_STRIDE = 1024         Texture row stride (256 px * 4 bytes)
;   BLT_DST_STRIDE = 2560         Output row stride (640 px * 4 bytes)
;   BLT_MODE7_TEX_W = 255         Texture width MASK (wraps U to 0-255)
;   BLT_MODE7_TEX_H = 255         Texture height MASK (wraps V to 0-255)
;
; === MODE7 AFFINE PARAMETERS ===
;
; These define the affine transformation. For each screen pixel (px, py):
;   u = u0 + px * du_col + py * du_row
;   v = v0 + px * dv_col + py * dv_row
;   output[py][px] = texture[(u >> 16) & tex_w][(v >> 16) & tex_h]
;
;   u0, v0:           Starting texture coordinates (16.16 fixed-point)
;   du_col, dv_col:   UV change per column (per pixel horizontally)
;   du_row, dv_row:   UV change per row (per pixel vertically)
;
; From the rotation matrix [[CA, -SA], [SA, CA]]:
;   du_col =  CA       dv_col =  SA
;   du_row = -SA       dv_row =  CA
;
; The -SA for du_row is computed inline using IE32's XOR+ADD negate pattern.
;
; MASKS = 255 (NOT 256)?
; The Mode7 blitter uses bitwise AND with these masks to wrap texture
; coordinates: (u >> 16) & 255 maps any coordinate to 0-255, creating
; the infinite tiling effect. This is a standard power-of-2 texture
; wrapping trick used in hardware since the SNES.
; ============================================================================
render_mode7:
    LDA #5
    STA @BLT_OP

    LDA #TEXTURE_BASE
    STA @BLT_SRC
    LDA @VAR_DRAW_FB
    STA @BLT_DST

    LDA #RENDER_W
    STA @BLT_WIDTH
    LDA #RENDER_H
    STA @BLT_HEIGHT

    LDA #TEX_STRIDE
    STA @BLT_SRC_STRIDE
    LDA #LINE_BYTES_V
    STA @BLT_DST_STRIDE

    LDA #255
    STA @BLT_MODE7_TEX_W
    STA @BLT_MODE7_TEX_H

    ; --- Load pre-computed affine parameters ---
    LDA @VAR_U0
    STA @BLT_MODE7_U0

    LDA @VAR_V0
    STA @BLT_MODE7_V0

    LDA @VAR_CA
    STA @BLT_MODE7_DU_COL       ; du_col = CA

    LDA @VAR_SA
    STA @BLT_MODE7_DV_COL       ; dv_col = SA

    ; du_row = -SA (negate SA using XOR+ADD)
    ; The rotation matrix requires du_row to be the negative of SA.
    ; Since IE32 has no NEG instruction, we apply two's complement negate.
    XOR A, #0xFFFFFFFF
    ADD A, #1                     ; A = -SA
    STA @BLT_MODE7_DU_ROW       ; du_row = -SA

    LDA @VAR_CA
    STA @BLT_MODE7_DV_ROW       ; dv_row = CA

    ; --- Trigger the blit and wait for completion ---
    ; BLT_CTRL = 1 starts the operation. We then poll BLT_CTRL bit 1
    ; (busy flag) until it clears. BLT_STATUS bit 1 is DONE, not BUSY.
    ; The Mode7 blit processes all 307,200
    LDA #1
    STA @BLT_CTRL

rm7_wait:
    LDA @BLT_CTRL
    AND A, #2
    JNZ A, rm7_wait

    RTS

; ============================================================================
; PRESENT COMPLETED FRAME
; ============================================================================
; Points the VideoChip at the completed render buffer. No full-screen copy is
; needed, so the blitter is free for the next Mode7 render.
; ============================================================================
present_frame:
    LDA @VAR_DRAW_FB
    STA @VIDEO_FB_BASE
    RTS

; ============================================================================
; SWAP DRAW BUFFER
; ============================================================================
swap_draw_buffer:
    LDA @VAR_DRAW_FB
    SUB A, #BACK_BUFFER_A
    JNZ A, use_buffer_a
    LDA #BACK_BUFFER_B
    STA @VAR_DRAW_FB
    RTS
use_buffer_a:
    LDA #BACK_BUFFER_A
    STA @VAR_DRAW_FB
    RTS

; ============================================================================
; ADVANCE ANIMATION
; ============================================================================
; Increments the angle and scale accumulators by their respective rates,
; then wraps both to 16 bits (0x0000-0xFFFF).
;
; The 8.8 fixed-point format means:
;   - Upper 8 bits: table index (0-255)
;   - Lower 8 bits: fractional part (sub-index precision)
;
; ANGLE_INC=313 advances the angle by ~1.22 table entries per frame,
; completing a full rotation every ~210 frames (~3.5 seconds at 60 FPS).
;
; SCALE_INC=104 advances the zoom by ~0.41 table entries per frame,
; completing a full zoom cycle every ~630 frames (~10.5 seconds).
;
; The AND #0xFFFF wraps the accumulator to 16 bits, ensuring the upper
; byte (table index) naturally wraps from 255 back to 0 via overflow.
; ============================================================================
advance_animation:
    LDA @VAR_ANGLE_ACC
    ADD A, #ANGLE_INC
    AND A, #0xFFFF
    STA @VAR_ANGLE_ACC

    LDA @VAR_SCALE_ACC
    ADD A, #SCALE_INC
    AND A, #0xFFFF
    STA @VAR_SCALE_ACC

    RTS

; ============================================================================
; SINE TABLE - 256 Entries, 32-bit Sign-Extended
; ============================================================================
; Precomputed sine values for angles 0-255 (representing 0 to 2*pi).
; Each entry is round(sin(i * 2*pi / 256) * 256).
; Values range from -256 to +256 (representing -1.0 to +1.0 in 8.8 FP).
;
; 256 ENTRIES?
; 256 = 2^8, so the table index is exactly the upper byte of our 8.8
; fixed-point angle accumulator. No additional masking or scaling is
; needed beyond shifting right by 8 and masking to 8 bits. 256 entries
; give ~1.4 degree resolution, which is far below the perceptible
; threshold for smooth rotation animation at 60 FPS.
;
; TRUE SINE (NOT TRIANGLE WAVE)?
; A triangle wave approximation would be cheaper to compute (and wouldn't
; need a table at all), but it introduces ~29% error at 45 degrees. This
; error manifests as visible speed variation -- the rotation appears to
; accelerate and decelerate within each quadrant, destroying the smooth
; circular motion. True sine gives perfect circular rotation with constant
; angular velocity.
;
; IE32-SPECIFIC: 32-BIT ENTRIES?
; IE32's .word directive emits 32-bit values (unlike most assemblers where
; .word is 16-bit). This means negative values are stored already sign-
; extended to 32 bits: -6 is stored as 0xFFFFFFFA, -256 as 0xFFFFFF00.
; When loaded with LDA [A], no sign-extension is needed -- the value is
; immediately usable as a signed 32-bit integer. This eliminates what
; would otherwise be a separate sign-extension step on every table lookup.
;
; TABLE LAYOUT:
;   Index   0-63:   Quadrant 1 (0 to +256)    ascending
;   Index  64-127:  Quadrant 2 (+256 to 0)     descending
;   Index 128-191:  Quadrant 3 (0 to -256)     descending
;   Index 192-255:  Quadrant 4 (-256 to 0)     ascending
;
; COSINE TRICK: cos(angle) = sin(angle + 64)
; Since 64 entries = 90 degrees, adding 64 to the sine table index gives
; cosine. This avoids needing a separate cosine table.
;
; MEMORY FOOTPRINT: 256 entries * 4 bytes = 1024 bytes (1 KB)
; ============================================================================
sine_table:
    ; Quadrant 1: indices 0-63, values rise from 0 to +256
    .word 0,6,13,19,25,31,38,44,50,56,62,68,74,80,86,92
    .word 98,104,109,115,121,126,132,137,142,147,152,157,162,167,172,177
    .word 181,185,190,194,198,202,206,209,213,216,220,223,226,229,231,234
    .word 237,239,241,243,245,247,248,250,251,252,253,254,255,255,256,256
    ; Quadrant 2: indices 64-127, values fall from +256 to 0
    .word 256,256,256,255,255,254,253,252,251,250,248,247,245,243,241,239
    .word 237,234,231,229,226,223,220,216,213,209,206,202,198,194,190,185
    .word 181,177,172,167,162,157,152,147,142,137,132,126,121,115,109,104
    .word 98,92,86,80,74,68,62,56,50,44,38,31,25,19,13,6
    ; Quadrant 3: indices 128-191, values fall from 0 to -256
    ; Negative values are stored as 32-bit two's complement (sign-extended).
    ; Example: -6 = 0xFFFFFFFA, -256 = 0xFFFFFF00
    .word 0,0xFFFFFFFA,0xFFFFFFF3,0xFFFFFFED,0xFFFFFFE7,0xFFFFFFE1,0xFFFFFFDA,0xFFFFFFD4,0xFFFFFFCE,0xFFFFFFC8,0xFFFFFFC2,0xFFFFFFBC,0xFFFFFFB6,0xFFFFFFB0,0xFFFFFFAA,0xFFFFFFA4
    .word 0xFFFFFF9E,0xFFFFFF98,0xFFFFFF93,0xFFFFFF8D,0xFFFFFF87,0xFFFFFF82,0xFFFFFF7C,0xFFFFFF77,0xFFFFFF72,0xFFFFFF6D,0xFFFFFF68,0xFFFFFF63,0xFFFFFF5E,0xFFFFFF59,0xFFFFFF54,0xFFFFFF4F
    .word 0xFFFFFF4B,0xFFFFFF47,0xFFFFFF42,0xFFFFFF3E,0xFFFFFF3A,0xFFFFFF36,0xFFFFFF32,0xFFFFFF2F,0xFFFFFF2B,0xFFFFFF28,0xFFFFFF24,0xFFFFFF21,0xFFFFFF1E,0xFFFFFF1B,0xFFFFFF19,0xFFFFFF16
    .word 0xFFFFFF13,0xFFFFFF11,0xFFFFFF0F,0xFFFFFF0D,0xFFFFFF0B,0xFFFFFF09,0xFFFFFF08,0xFFFFFF06,0xFFFFFF05,0xFFFFFF04,0xFFFFFF03,0xFFFFFF02,0xFFFFFF01,0xFFFFFF01,0xFFFFFF00,0xFFFFFF00
    ; Quadrant 4: indices 192-255, values rise from -256 to 0
    .word 0xFFFFFF00,0xFFFFFF00,0xFFFFFF00,0xFFFFFF01,0xFFFFFF01,0xFFFFFF02,0xFFFFFF03,0xFFFFFF04,0xFFFFFF05,0xFFFFFF06,0xFFFFFF08,0xFFFFFF09,0xFFFFFF0B,0xFFFFFF0D,0xFFFFFF0F,0xFFFFFF11
    .word 0xFFFFFF13,0xFFFFFF16,0xFFFFFF19,0xFFFFFF1B,0xFFFFFF1E,0xFFFFFF21,0xFFFFFF24,0xFFFFFF28,0xFFFFFF2B,0xFFFFFF2F,0xFFFFFF32,0xFFFFFF36,0xFFFFFF3A,0xFFFFFF3E,0xFFFFFF42,0xFFFFFF47
    .word 0xFFFFFF4B,0xFFFFFF4F,0xFFFFFF54,0xFFFFFF59,0xFFFFFF5E,0xFFFFFF63,0xFFFFFF68,0xFFFFFF6D,0xFFFFFF72,0xFFFFFF77,0xFFFFFF7C,0xFFFFFF82,0xFFFFFF87,0xFFFFFF8D,0xFFFFFF93,0xFFFFFF98
    .word 0xFFFFFF9E,0xFFFFFFA4,0xFFFFFFAA,0xFFFFFFB0,0xFFFFFFB6,0xFFFFFFBC,0xFFFFFFC2,0xFFFFFFC8,0xFFFFFFCE,0xFFFFFFD4,0xFFFFFFDA,0xFFFFFFE1,0xFFFFFFE7,0xFFFFFFED,0xFFFFFFF3,0xFFFFFFFA

; ============================================================================
; RECIPROCAL TABLE - 256 Entries, 32-bit Unsigned
; ============================================================================
; Precomputed zoom factors for the Mode7 affine transformation.
; Each entry is round(256 / (0.5 + sin(i * 2*pi / 256) * 0.3)).
;
; THIS FORMULA?
; The expression (0.5 + sin(i) * 0.3) oscillates between 0.2 and 0.8.
; Taking the reciprocal and scaling by 256 gives values from ~320 to ~1280.
;
;   - The 0.5 baseline keeps the denominator always positive (minimum 0.2),
;     preventing division by zero or negative zoom (which would flip the
;     texture -- visually jarring). Without this offset, when sin(i) = -1,
;     the denominator would be -0.3, causing an inverted and extremely
;     zoomed-in frame.
;
;   - The 0.3 amplitude controls how dramatically the zoom oscillates.
;     Smaller values (e.g., 0.1) would give subtle zoom; larger values
;     (e.g., 0.5) would range from extreme close-up to very far away.
;     0.3 gives a visually balanced range: the texture is always
;     recognizable but clearly zooming in and out.
;
;   - The 256 numerator scales the result into a useful integer range for
;     the signed multiply with sine/cosine values (which are also scaled
;     by 256). The product CA = cos * recip is therefore in 16.16-ish
;     fixed-point, suitable for the blitter's 16.16 FP parameter format.
;
; PRE-COMPUTE?
; IE32 has no division instruction at all. Computing reciprocals at
; runtime would require a software division routine -- expensive and
; unnecessary when the values are deterministic (indexed by a known
; accumulator). A 1 KB table eliminates all runtime division.
;
; TABLE SHAPE (zoom over one full cycle):
;   Index 0:     512 (baseline zoom -- texture at 1:2 scale)
;   Index 64:    320 (most zoomed in -- texture appears larger)
;   Index 128:   512 (back to baseline)
;   Index 192:  1280 (most zoomed out -- texture appears smaller)
;   Index 255:   520 (approaching baseline again)
;
; MEMORY FOOTPRINT: 256 entries * 4 bytes = 1024 bytes (1 KB)
;
; IE32-SPECIFIC: All values are positive, so no sign-extension concerns.
; They are stored as plain unsigned 32-bit integers.
; ============================================================================
recip_table:
    .word 512,505,497,490,484,477,471,464,458,453,447,441,436,431,426,421
    .word 416,412,407,403,399,395,391,388,384,381,377,374,371,368,365,362
    .word 359,357,354,352,350,348,345,343,342,340,338,336,335,333,332,331
    .word 329,328,327,326,325,324,324,323,322,322,321,321,321,320,320,320
    .word 320,320,320,320,321,321,321,322,322,323,324,324,325,326,327,328
    .word 329,331,332,333,335,336,338,340,342,343,345,348,350,352,354,357
    .word 359,362,365,368,371,374,377,381,384,388,391,395,399,403,407,412
    .word 416,421,426,431,436,441,447,453,458,464,471,477,484,490,497,505
    .word 512,520,528,536,544,553,561,571,580,589,599,610,620,631,642,653
    .word 665,676,689,701,714,727,740,754,768,782,797,812,827,842,858,873
    .word 889,905,922,938,955,972,988,1005,1022,1038,1055,1071,1087,1103,1119,1134
    .word 1149,1163,1177,1190,1202,1214,1225,1235,1244,1252,1260,1266,1271,1275,1278,1279
    .word 1280,1279,1278,1275,1271,1266,1260,1252,1244,1235,1225,1214,1202,1190,1177,1163
    .word 1149,1134,1119,1103,1087,1071,1055,1038,1022,1005,988,972,955,938,922,905
    .word 889,873,858,842,827,812,797,782,768,754,740,727,714,701,689,676
    .word 665,653,642,631,620,610,599,589,580,571,561,553,544,536,528,520

; ============================================================================
; MUSIC DATA
; ============================================================================
; Embedded AHX music file (Amiga tracker format).
;
; AHX (Abyss' Highest eXperience) is a 4-channel waveform synthesis tracker
; format from the Amiga demoscene. Unlike SID (which uses a 6502 CPU core)
; or PSG (which uses a Z80 core), AHX playback is handled natively by the
; Intuition Engine's AHX audio engine -- no secondary CPU is involved.
;
; The file is included verbatim using .incbin. The audio subsystem parses
; the AHX header, extracts instrument definitions and pattern data, and
; plays the music autonomously. The main CPU has zero per-frame overhead
; for audio after the initial AHX_PLAY_CTRL write.
;
; The ahx_data_end label immediately after the .incbin allows us to compute
; the file size at assemble time: size = ahx_data_end - ahx_data.
; ============================================================================
; ============================================================================
; TEXTURE DATA - 256x256 RGBA RAW IMAGE
; ============================================================================
texture_data:
.incbin "../assets/rotozoomtexture_ie32.raw"

ahx_data:
.incbin "../assets/music/Fairlightz.ahx"
ahx_data_end:
