/// Draw one frame via the `draw` closure and read the software framebuffer back
/// **without normalization** — the returned [`Image`] is in raw rlsw readback
/// form: bytes are BGRA (R and B swapped vs. what was drawn) and rows are
/// Y-inverted (`y_img = (h - 1) - y_screen`). Prefer [`render_frame`] unless you
/// specifically need the raw readback; see `notes/ws4b-complete.md`.
///
/// `EndDrawing`-on-drop flushes rlsw into the memory framebuffer before
/// [`load_image_from_screen`](RaylibHandle::load_image_from_screen) reads it.
#[inline]
#[must_use]
pub fn render_frame_raw<F: FnOnce(&mut RaylibDrawHandle<'_>)>(
    rl: &mut RaylibHandle,
    thread: &RaylibThread,
    draw: F,
) -> Image {
    {
        let mut d = rl.begin_drawing(thread);
        draw(&mut d);
    } // Drop here calls EndDrawing, flushing rlsw into the memory framebuffer.
    rl.load_image_from_screen(thread)
}

/// Draw one frame via the `draw` closure, then read the software framebuffer
/// back as a **normalized** top-left RGBA [`Image`].
///
/// The raw rlsw readback is BGRA + Y-inverted (deterministic on every OS; see
/// `notes/ws4b-complete.md`). This function corrects both so callers use natural
/// draw coordinates and colors: a `Color::RED` rectangle reads back as red at the
/// screen `(x, y)` it was drawn at. Use [`render_frame_raw`] for the un-normalized
/// buffer.
#[inline]
#[must_use]
pub fn render_frame<F: FnOnce(&mut RaylibDrawHandle<'_>)>(
    rl: &mut RaylibHandle,
    thread: &RaylibThread,
    draw: F,
) -> Image {
    let mut img = render_frame_raw(rl, thread, draw);
    normalize_readback(&mut img);
    img
}

/// Correct the rlsw readback in place: flip vertically and swap the R/B channels,
/// yielding a true top-left RGBA image.
fn normalize_readback(img: &mut Image) {
    // Fix Y-inversion using the existing safe image op.
    img.flip_vertical();

    // Fix the BGRA-as-RGBA byte order by swapping byte 0 (R) and byte 2 (B) of
    // every 4-byte pixel. The readback is always PIXELFORMAT_UNCOMPRESSED_R8G8B8A8.
    debug_assert_eq!(
        img.format(),
        crate::consts::PixelFormat::PIXELFORMAT_UNCOMPRESSED_R8G8B8A8,
        "normalize_readback assumes 32-bit RGBA readback"
    );
    let len = (img.width() * img.height()) as usize * 4;
    // SAFETY: `img` is a freshly loaded screen image in 32-bit RGBA8 format, so
    // its data buffer is exactly `width * height * 4` valid, initialized bytes.
    // We only swap two in-bounds bytes per pixel; no aliasing (single &mut slice).
    unsafe {
        let bytes = std::slice::from_raw_parts_mut(img.data() as *mut u8, len);
        for px in bytes.chunks_exact_mut(4) {
            px.swap(0, 2);
        }
    }
}

//! Headless render-test harness (software_renderer / Memory platform).
//!
//! raylib is single-init per process, so a Tier-2 test file inits **once** via
//! [`with_headless`], draws inside the closure, then probes the framebuffer.
//!
//! [`render_frame`] returns a **normalized** top-left RGBA image (natural draw
//! coordinates and colors). [`render_frame_raw`] returns the raw rlsw readback
//! (BGRA + Y-inverted) for callers that need it.

cargo build -p raylib --no-default-features --features software_renderer

git add raylib/src/test_harness.rs
git commit -m "feat(ws5): normalize render_frame to top-left RGBA; add render_frame_raw

Co-Authored-By: Claude Opus 4.7 <[email protected]>"

//! WS4b Tier-2 (updated WS5-prep): software-rendered shapes land the expected
//! pixels. Headless, no GPU. Uses the normalized `render_frame`, so probes are in
//! natural top-left coordinates with the drawn colors (no BGRA / Y-flip
//! compensation — `render_frame` handles both).
#![cfg(feature = "software_renderer")]
use raylib::prelude::*;
use raylib::test_harness::{assert_pixel, render_frame, with_headless};

// One `#[test]` per file: `with_headless` calls `InitWindow`, which raylib permits
// only once per process, so every probe shares a single headless context.
#[test]
fn shapes_render_expected_pixels() {
    with_headless(64, 64, |rl, thread| {
        let img = render_frame(rl, thread, |d| {
            d.clear_background(Color::BLACK);
            d.draw_rectangle(8, 8, 16, 16, Color::RED); // solid red block, screen (8..23, 8..23)
            d.draw_circle(48, 48, 8.0, Color::GREEN); // green disc, screen centre (48,48)
            d.draw_line(0, 0, 63, 0, Color::BLUE); // top edge blue, screen y≈0
        });

        // Background: well outside every primitive.
        assert_pixel(&img, 40, 20, Color::BLACK, 8);

        // Rectangle interior reads back as the drawn red.
        assert_pixel(&img, 16, 16, Color::RED, 16);

        // Circle centre reads back as the drawn green.
        assert_pixel(&img, 48, 48, Color::GREEN, 16);

        // Top-edge line reads back as the drawn blue. rlsw places the topmost line
        // one row in, so probe screen y=1 rather than y=0.
        assert_pixel(&img, 32, 1, Color::BLUE, 16);
    });
}

cargo test -p raylib --no-default-features --features software_renderer,SUPPORT_MODULE_RTEXTURES,SUPPORT_MODULE_RSHAPES,SUPPORT_MODULE_RTEXT,SUPPORT_MODULE_RMODELS,SUPPORT_MODULE_RAUDIO --test render_shapes -- --test-threads=1

git add raylib/tests/render_shapes.rs
git commit -m "test(ws5): probe shapes in natural coords via normalized render_frame

Co-Authored-By: Claude Opus 4.7 <[email protected]>"

cargo test -p raylib --no-default-features --features software_renderer,SUPPORT_MODULE_RTEXTURES,SUPPORT_MODULE_RSHAPES,SUPPORT_MODULE_RTEXT,SUPPORT_MODULE_RMODELS,SUPPORT_MODULE_RAUDIO --test render_text -- --test-threads=1

//! WS4b Tier-2 (WS5-prep): drawn text produces foreground pixels within its
//! bounds. Headless. Uses the normalized `render_frame`; the whole-image white
//! scan is orientation/channel agnostic.

git add raylib/tests/render_text.rs
git commit -m "test(ws5): note normalized harness in render_text doc

Co-Authored-By: Claude Opus 4.7 <[email protected]>"

cargo test -p raylib --no-default-features --features software_renderer,SUPPORT_MODULE_RTEXTURES,SUPPORT_MODULE_RSHAPES,SUPPORT_MODULE_RTEXT,SUPPORT_MODULE_RMODELS,SUPPORT_MODULE_RAUDIO --test render_shapes --test render_text -- --test-threads=1

cargo clippy -p raylib --no-default-features --features software_renderer

git add -A
git commit -m "chore(ws5): clippy clean for normalized harness

Co-Authored-By: Claude Opus 4.7 <[email protected]>"