BabylonJS/Babylon.js · error · Error

Sample2DRgbaToRef: widthPx and heightPx must be positive.

Error message

Sample2DRgbaToRef: widthPx and heightPx must be positive.

What it means

Sample2DRgbaToRef samples an RGBA LUT stored in a flat typed array sized widthPx*heightPx*4. Non-positive dimensions make sampling math meaningless, so the function validates them up front and throws. Callers such as SampleLutToRef and getDiffuseSkyIrradianceToRef pass LUT dimensions that must come from valid texture descriptors.

Source

Thrown at packages/dev/addons/src/atmosphere/sampling.ts:46

 * @param v - The v coordinate to sample.
 * @param widthPx - The width of the texture in texels.
 * @param heightPx - The height of the texture in texels.
 * @param data - The texture data to sample.
 * @param result - The color to store the sample.
 * @param normalizeFunc - The function to normalize the texel values. Default is to divide by 255. Pass null for no normalization.
 * @returns The result color.
 */
export function Sample2DRgbaToRef<T extends IColor4Like>(
    u: number,
    v: number,
    widthPx: number,
    heightPx: number,
    data: Uint8Array | Uint16Array | Float32Array,
    result: T,
    normalizeFunc: ((value: number) => number) | null = DefaultNormalize
): T {
    if (widthPx <= 0 || heightPx <= 0) {
        throw new Error("Sample2DRgbaToRef: widthPx and heightPx must be positive.");
    }

    const expectedLength = widthPx * heightPx * 4;
    if (data.length < expectedLength) {
        throw new Error(`Sample2DRgbaToRef: data length (${data.length}) is less than required (${expectedLength}).`);
    }

    // Default to clamping behavior, but could support others.
    u = Clamp(u);
    v = Clamp(v);

    // Compute 4 nearest neighbor texels.
    const fractionalTexelX = Math.max(u * widthPx - 0.5, 0);
    const fractionalTexelY = Math.max(v * heightPx - 0.5, 0);
    const xLeft = Math.floor(fractionalTexelX);
    const xRight = Math.min(xLeft + 1, widthPx - 1);
    const yBottom = Math.floor(fractionalTexelY);
    const yTop = Math.min(yBottom + 1, heightPx - 1);

View on GitHub (pinned to 0592b347b8)

Solutions

Validate LUT dimensions before sampling: ensure widthPx > 0 && heightPx > 0 and fall back to configured defaults (e.g. transmittance 256x64).
Fix where the dimensions come from — check the texture creation options passed to the Atmosphere physical properties / LUT generation.
Guard call sites: skip sampling until the LUT has been generated with valid dimensions.

Example fix

// before
sample.Sample2DRgbaToRef(u, v, lut.width, lut.height, lutData, result); // width may be 0
// after
if (lut.width > 0 && lut.height > 0) {
  sample.Sample2DRgbaToRef(u, v, lut.width, lut.height, lutData, result);
}

Defensive patterns

Strategy: validation

Validate before calling

function assertValidLutDims(w: number, h: number): void {
  if (!(w > 0) || !(h > 0)) throw new Error(`bad LUT dims ${w}x${h}`);
}
assertValidLutDims(lut.width, lut.height);

Type guard

const arePositiveDims = (d: { width: number; height: number }): d is { width: number; height: number } =>
  d.width > 0 && d.height > 0;

Try / catch

try {
  Sample2DRgbaToRef(u, v, w, h, data, out);
} catch (e) {
  if (String(e).includes("must be positive")) {
    // regenerate LUT with default dimensions before retrying
  } else throw e;
}

Prevention

Never construct LUTs with computed sizes without validating > 0.
Delay sampling until the LUT generation pass has completed.
Keep configured LUT resolutions as named constants, not derived values.

When it happens

Trigger: Calling Sample2DRgbaToRef (directly or via SampleLutToRef / getDiffuseSkyIrradianceToRef) with widthPx <= 0 or heightPx <= 0, e.g. a transmittance/multiscattering LUT created with zero size or dimension read before initialization.

Common situations: LUT texture created with size 0 because options had invalid dimensions or a compute pass failed; reading width/height from an uninitialized object; integer truncation producing 0 for very small configured sizes.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of BabylonJS/Babylon.js@0592b347b8 (2026-08-30). Data as JSON: /api/errors/6bdac102475d1b69. Report an issue: GitHub.