TextureResourceManager

Builds a stable texture resource key.

The key is composed of two logical parts:

1. Source image identity Describes where the original image comes from or how it can be uniquely identified.

   Supported prefixes:

   • res: A precomputed resource key provided by the GLTF parser. This is the preferred path for GLTF/GLB textures.

     Example: res:gltf-image|bytes:9a4c1f20|mime:image/png|len:24576

   • uri: A normalized external image URI. Used when the texture comes from an external image file. The URI should be resolved relative to the GLTF file path.

     Example: uri:https://example.com/models/tree/textures/baseColor.png

   • fp: A content fingerprint calculated from image pixels. This is an expensive fallback path because it may require canvas readback. It can also fail for cross-origin images.

     Example: fp:7f21ab09

   • obj: A last-resort object identity key. Used only when no resourceKey, URI, or content fingerprint is available. This avoids accidental sharing between unrelated images.

     Example: obj:3

2. GPU texture creation parameters. Describes how the source image is uploaded to WebGL. The same source image may require different GPU textures if creation parameters differ.

   Supported fields:

   • fmt: Internal texture format passed to Handler.createTextureDefault(...). If absent, "fmt:default" means the default internal format is used.

     Example: fmt:default fmt:6408

   • wrap: Texture wrapping/filtering parameter passed to Handler.createTextureDefault(...). If absent, "wrap:default" means the default texture parameter is used.

     Example: wrap:default wrap:10497

   • mime: MIME type of the original image, if available. Used as an additional discriminator and for debugging.

     Example: mime:image/png

   • len: Original image byte length, if available. Used as an additional cheap discriminator, but not as the primary identity.

     Example: len:24576

Important:

• GLTF texture/image name is intentionally not used as a primary identity key. Names may be missing, duplicated, or different for the same binary image.

• The preferred identity source is resourceKey from the GLTF parser.

• The fallback order is: resourceKey -> normalized URI -> content fingerprint -> object identity.

• The final key must distinguish not only the source image, but also the GPU upload parameters that may affect the resulting WebGLTexture.

Returns an existing texture for the same resource or creates a new one. Increases reference count for reused textures.

Deletes all managed GPU textures and clears manager state.

Returns number of unique managed texture entries.

Returns debug statistics for managed textures.

Releases one texture reference. Deletes GPU texture only when the reference count reaches zero.