glReadPixels scalar and PACK contract — 2026-11-02

No scalar-conversion or packing defect was demonstrated for the tested RGBA8 software surfaces. One error-code defect was demonstrated and repaired: GL_BITMAP with a component format returned GL_INVALID_OPERATION (0x502) instead of GL_INVALID_ENUM (0x500). The production change only adds this validation before the existing unsupported-index/depth checks.

The static analysis preceded shared edits and execution. Primary source: OpenGL 1.1 specification, 4 March 1997, §§2.1, 2.5, 3.6.3 and 4.3.2; tables 3.6, 4.5 and 4.7.

For a final clamped component f, the table's conversions are:

Destination Real-valued conversion
Unsigned n-bit integer (2^n − 1) f
Signed n-bit integer ((2^n − 1) f − 1) / 2
FLOAT f in the client's floating representation

The signed formula differs from multiplying by the positive signed maximum. This difference alone is insufficient evidence of an output defect here. For f=k/255, the specified signed result is integral for odd k and a half-integer for even k. The existing implementation selects an adjacent integer in each half-integer case. Table 4.7 does not prescribe a tie direction; the test accepts either adjacent integer there. Black is near zero, not the most negative signed integer. White reaches the positive maximum.

The independent fixtures use these results, derived before runtime:

Source byte k 0 51 85 128 170 204 255
UNSIGNED_BYTE 0 51 85 128 170 204 255
BYTE, before integer rounding −0.5 25 42 63.5 84.5 101.5 127
UNSIGNED_SHORT 0 13107 21845 32896 43690 52428 65535
SHORT, before integer rounding −0.5 6553 10922 16447.5 21844.5 26213.5 32767
UNSIGNED_INT 0 858993459 1431655765 2155905152 2863311530 3435973836 4294967295
INT, before integer rounding −0.5 429496729 715827882 1077952575.5 1431655764.5 1717986917.5 2147483647
FLOAT, binary32 bits 00000000 3e4ccccd 3eaaaaab 3f008081 3f2aaaab 3f4ccccd 3f800000

PACK placement uses component count C, scalar size S, row pixels L (ROW_LENGTH or requested width), and alignment A. The byte stride is CSL when S >= A, otherwise A ceil(CSL/A). The initial offset is SKIP_ROWS*stride + SKIP_PIXELS*CS. Byte swapping reverses each scalar's bytes; it preserves component order. LSB_FIRST concerns bitmap bits and has no scalar effect. Invalid enums/sizes and calls inside Begin/End preserve the destination. BITMAP requires an index format.

test/test-opengl-readpixels-scalars.js resolves real opengl32 thunks using WAT LoadLibrary/GetProcAddress and dispatches them through win32_dispatch. It checks stdcall cleanup, preserved registers and argument-stack bytes. Both direct native software rendering and the queued native renderer plus software consumer execute the same cases. A fenced native point and its raw surface pixel establish that the queued raster path actually ran.

Coverage includes all seven scalar types; black, middle fractions and white; swap on/off; alignments 1/2/4/8; default and explicit row length; two distinct rows; skipped rows/pixels; unaligned destination; component order; individual channels, RGB/RGBA, luminance and BGR/BGRA. Literal expected row offsets avoid copying production stride calculations. All 1,024 destination bytes are checked, including prefix, skipped regions, row padding and suffix guards. PACK_LSB_FIRST and unrelated UNPACK state are isolation controls. Wrong-endian interpretation and a deliberately changed prefix guard must each fail the oracle. Invalid formats/types, DOUBLE, negative/zero sizes, COLOR_INDEX, Begin/End, and bitmap-format errors also check untouched output.

Evidence is ignored under scratch/runs/20261102-gl-readpixels-scalar-contract/. The final test passes 1,258 assertions and two negative controls per route. With the committed pre-repair bridge from 71fb8fb279369abfff4c4e5ad64c143921ae0240 loaded in memory, the identical final test passes its 1,250 scalar/PACK/control checks on both routes, then fails on GL_BITMAP + GL_RED: actual 1282, expected 1280. old-exact-final-{direct,queued}.log retain these failures; scalars-final-{direct,queued}.log retain repaired passes. Earlier point-control fixture failures are retained separately: its observed native row was corrected, and queued raw inspection gained an explicit fence. They were not conversion failures.

Existing drawable/color-buffer tests pass directly and queued, alongside color mask, unpack alignment, client attributes, command stream, WAT encoder/worker, WebGL drawable recorder and WGL availability regressions. The full locked build passes. No browser, boat, original game, download or optimization was used. This establishes the bounded RGBA8 software contract; it does not qualify other framebuffer precisions, pixel-transfer operations, depth/stencil readback or new hardware rendering.

Both required predecessor terminal results, completion events, exact final AUTHOR RELEASE statements and helper absence were verified before claims and execution: GTA b0ec7da81, then WebGL drawables 71fb8fb27; all 354 recorded helpers were independently absent. Box ID/state/expiry: N/A; coordinator lifecycle unchanged. No further scalar or PACK implementation change is warranted by this evidence.