fix(BillboardCollection): Fix precision loss in billboard image texcoords

[donmccurdy]

Description

Currently billboards compute texture coordinates (in 0–1 UV space) for each image in the texture atlas:

cesium/packages/engine/Source/Renderer/TextureAtlas.js

Lines 195 to 206 in ee2b381

	/**
	* Get the texture coordinates for reading the associated image in shaders.
	* @param {number} index The index of the image region.
	* @param {BoundingRectangle} [result] The object into which to store the result.
	* @return {BoundingRectangle} The modified result parameter or a new BoundingRectangle instance if one was not provided.
	* @private
	* @example
	* const index = await atlas.addImage("myImage", image);
	* const rectangle = atlas.computeTextureCoordinates(index);
	* BoundingRectangle.pack(rectangle, bufferView);
	*/
	TextureAtlas.prototype.computeTextureCoordinates = function (index, result) {

Texture coordinates are then quantized to 12 bits:

cesium/packages/engine/Source/Core/AttributeCompression.js

Lines 308 to 317 in ee2b381

	/**
	* Pack texture coordinates into a single float. The texture coordinates will only preserve 12 bits of precision.
	*
	* @param {Cartesian2} textureCoordinates The texture coordinates to compress. Both coordinates must be in the range 0.0-1.0.
	* @returns {number} The packed texture coordinates.
	*
	*/
	AttributeCompression.compressTextureCoordinates = function (
	textureCoordinates,
	) {

On testing all valid pixel offsets for all power-of-two atlas sizes...

const src = {x: 0, y: 0}, dst = {x: 0, y: 0};
for (let exp = 1; exp <= 12; exp++) {
  const width = 2 ** exp;
  for (let x = 0; x <= width; x++) {
    src.x = x / width;

    const encoded = AttributeCompression.compressTextureCoordinates(src);
    AttributeCompression.decompressTextureCoordinates(encoded, dst);

    const dstX = Math.round(dst.x * width);
    assert(dstX === x, `❌ Expected dstX=${dstX} to be ${x}`);
  }
}

... we find coordinates off by 1px about 25% of the time, which I believe explains the remaining issues from #5154. While we could modify the texture compression code to fix this, (1) texture coordinates outside of billboards may not correspond to integer pixel offsets at all, and (2) it's worth stepping back to consider what we're trying to do:

Ultimately each Billboard must sample from its image in the texture atlas. Images have integer pixel offsets and integer dimensions, which cannot exceed maximum texture sizes of ~16K. We need to pack pairs of these integers into 32-bit vertex attribute components. We can achieve this more simply by packing two integers into one 32-bit float directly...

const encoded = x * (2 ** 16) + y;

... skipping both integer-to-float conversions and lossy quantization.

Preview:

TODO

Issue number and link

• Fixes Billboard clipped on right side #5154

Testing plan

Because coordinates and attribute packing differs in WebGL2 vs. WebGL1, and with or without instancing, we need to test multiple environments:

1. WebGL2, instancing
2. WebGL1, instancing
3. WebGL1, no instancing

WebGL2 guarantees instancing support, so we don't need to worry about that case. If #13042 is merged before this PR (preferred) then the WebGL1 vs. WebGL2 distinction is removed and we only need to worry about instanced vs. non-instanced code paths. Optionally instancing could be required (see #13053) but I've handled the non-instanced fallback here anyway.

More detailed test plan TBD.

Author checklist

• I have submitted a Contributor License Agreement
• I have added my name to CONTRIBUTORS.md
• I have updated CHANGES.md with a short summary of my change
• I have added or updated unit tests to ensure consistent code coverage
• I have updated the inline documentation, and included code examples where relevant
• I have performed a self-review of my code

PR Dependency Tree

• PR fix(textureatlas): Allocate texture space more incrementally on resize #13042
  • PR fix(BillboardCollection): Fix precision loss in billboard image texcoords #13050 👈

This tree was auto-generated by Charcoal

[github-actions]

Thank you for the pull request, @donmccurdy!

✅ We can confirm we have a CLA on file for you.