s3m-three 0.3.0 → 0.3.2

package/src/render/StyleMaterial.ts

@@ -208,6 +208,16 @@ export function createSharedUniforms(): StyleUniforms {
 const VERT_PARS = /* glsl */ `
   attribute float aBatchId;
   attribute vec3 aColor;
+  #ifdef S3M_ATLAS
+    attribute vec4 aAtlasRect;
+    #ifdef S3M_ATLAS_SEC
+      attribute vec4 aAtlasRect1;
+      attribute vec2 aSecUv;
+      varying vec2 vSecUv;
+      varying vec4 vSecRect;
+    #endif
+    varying vec4 vAtlasRect;
+  #endif
   // 实例化几何没有逐顶点 batchId：顶点是 base mesh 的，单体粒度落在实例上
   #ifdef USE_INSTANCING
     attribute float aInstanceBatchId;
@@ -267,6 +277,14 @@ const VERT_WORLD = /* glsl */ `
   vBatchId = s3mBatchRaw();
   vVertColor = aColor;
 
+  #ifdef S3M_ATLAS
+    vAtlasRect = aAtlasRect;
+    #ifdef S3M_ATLAS_SEC
+      vSecUv = aSecUv;
+      vSecRect = aAtlasRect1;
+    #endif
+  #endif
+
   #ifdef USE_INSTANCING
     mat3 s3mNormMat = mat3( modelMatrix ) * mat3( instanceMatrix );
   #else
@@ -276,6 +294,75 @@ const VERT_WORLD = /* glsl */ `
 `;
 
 const FRAG_PARS = /* glsl */ `
+  #ifdef S3M_ATLAS
+    varying vec4 vAtlasRect;
+    uniform vec2 uAtlasDim;
+    #ifdef S3M_ATLAS_SEC
+      uniform sampler2D uSecMap;
+      uniform vec2 uAtlasDim1;
+      varying vec2 vSecUv;
+      varying vec4 vSecRect;
+    #endif
+    /**
+     * 官方 CalculateMipLevel（vec2 版），逐字照抄 iClient3D 12.1.1。
+     * 用**未 fract** 的 uv 求屏幕空间导数 —— 先 fract 再求导会在平铺接缝处炸出
+     * 一个巨大导数，GPU 直接把整块砖采成最糊的 mip，表现为每块砖边缘一条暗线。
+     */
+    void s3mMipLevel( vec2 uv, vec2 texSize, float maxMip, out float mip ) {
+      vec2 dx = dFdx( uv * texSize.x );
+      vec2 dy = dFdy( uv * texSize.y );
+      float dotX = dot( dx, dx );
+      float dotY = dot( dy, dy );
+      float dMax = max( dotX, dotY );
+      float dMin = min( dotX, dotY );
+      float off = clamp( ( dMax - dMin ) / max( dMax + dMin, 1e-8 ), 0.0, 1.0 );
+      float d = dMax * ( 1.0 - off ) + dMin * off;
+      mip = clamp( 0.5 * log2( max( d, 1e-8 ) ), 0.0, maxMip - 1.62 );
+    }
+
+    /**
+     * 按指定 mip 档采样子区域（官方 czm_getTexColorForS3M 的内层循环体）。
+     *
+     * ★ 子区域 rect 的**右 1/3 不是贴图内容，是内联 mip 金字塔**：
+     *   mip0 只占左 2/3，右 1/3 从上往下依次堆 1/2、1/4、1/8 缩略图，总高恰好 = rect 高。
+     *   官方那句 width *= 2.0/3.0 就是为这个，不是「经验收缩系数」。
+     *   数值实证：14 个块 691 条子纹理里 96.7% 满足「右侧 1/3 ≈ 左 2/3 的 1/2 下采样」
+     *   （平均误差 6.8 vs 27.3）。
+     *   所以 mip > 0 时采样点必须右移到 x + 2/3·w，并下移到 (2^(m-1)-1)/2^(m-1)。
+     */
+    vec4 s3mAtlasLod( vec2 uv, vec2 translate, vec2 scale, vec2 texSize, sampler2D tex, float mip ) {
+      vec2 t = translate;
+      if ( mip > 0.0 ) {
+        t.x = translate.x + scale.x;
+        float temp = pow( 2.0, mip - 1.0 );
+        t.y = translate.y + scale.y * ( temp - 1.0 ) / temp;
+      }
+      float inv = 1.0 / pow( 2.0, mip );
+      vec2 o = fract( uv );
+      // 半纹素内缩，避免双线性把邻格内容混进来
+      vec2 guard = vec2( pow( 2.0, mip ) / texSize.x, pow( 2.0, mip ) / texSize.y );
+      o = clamp( o, guard, vec2( 1.0 ) - guard );
+      return texture2D( tex, o * inv * scale + t );
+    }
+
+    /**
+     * 图集采样入口：层级由 ceil/floor 两档各采一次再平均（官方同样做法），
+     * 因为内联金字塔只有 2 的整数次幂，中间档必须靠混合。
+     */
+    vec4 s3mAtlasUnit( vec2 uv, vec4 rect, vec2 atlasDim, sampler2D tex ) {
+      // 退化矩形 = 官方 batchId < 0：该纹理单元不参与合成
+      if ( rect.z <= 0.0 || rect.w <= 0.0 ) return vec4( 1.0 );
+      vec2 dimPx = vec2( rect.z * atlasDim.x, rect.w * atlasDim.y );
+      vec2 texSize = vec2( dimPx.x * ( 2.0 / 3.0 ), dimPx.y );
+      float maxMip = log2( max( min( texSize.x, texSize.y ), 1.0 ) );
+      vec2 scale = texSize / atlasDim;
+      float mip = 0.0;
+      s3mMipLevel( uv, texSize, maxMip, mip );
+      vec4 hi = s3mAtlasLod( uv, rect.xy, scale, texSize, tex, ceil( mip ) );
+      vec4 lo = s3mAtlasLod( uv, rect.xy, scale, texSize, tex, floor( mip ) );
+      return hi * 0.5 + lo * 0.5;
+    }
+  #endif
   uniform int uMode;
   uniform vec3 uColorA;
   uniform vec3 uColorB;
@@ -445,6 +532,14 @@ const FRAG_EMISSIVE = /* glsl */ `
   }
 `;
 
+const FRAG_BAKE = /* glsl */ `
+  #ifdef S3M_ATLAS_SEC
+    // 官方 getTextureColorForS3M = firstColor(base) * secColor(bake)，
+    // 两套独立的 rect / 尺寸（实测 base 11 条、bake 1 条，条数并不相同）
+    diffuseColor *= s3mAtlasUnit( vSecUv, vSecRect, uAtlasDim1, uSecMap );
+  #endif
+`;
+
 export interface StyledMaterialOptions {
   uniforms: StyleUniforms;
   map?: THREE.Texture | null;
@@ -454,6 +549,12 @@ export interface StyledMaterialOptions {
   opacity?: number;
   roughness?: number;
   flatShading?: boolean;
+  /** >0 时开启 alphaTest：镂空贴图（S3MBLOCK 图集）的透明片元直接丢弃，避免渲染成黑面 */
+  alphaTest?: number;
+  /** 贴图为 S3MBLOCK 图集：几何需带 aAtlasRect，平铺改由片元按子区域做 */
+  atlas?: boolean;
+  /** 图集材质的第二套纹理（官方 BakeTex，光照烘焙），与 base 相乘 */
+  secMap?: THREE.Texture | null;
 }
 
 /**
@@ -476,6 +577,7 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
     flatShading: opts.flatShading !== false,
     // 顶点色、贴图全部在自定义 chunk 里处理，不让 three 插手
     vertexColors: false,
+    alphaTest: opts.alphaTest ?? 0,
   }) as StyledMaterial;
 
   // 选中单体编号：每个 Mesh 独立，默认 -1 表示无选中
@@ -486,6 +588,15 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
   const uBatchTexWidth = { value: 1.0 };
   const uBatchTexActive = { value: 0 };
 
+  // 图集材质：只有几何确实带了 aAtlasRect 才开这个宏，否则缺属性会采到 (0,0) 的默认值
+  const atlas = !!opts.atlas && !!opts.map;
+  const secMap = atlas ? (opts.secMap ?? null) : null;
+  if (atlas) mat.defines = { ...(mat.defines as Record<string, string>), S3M_ATLAS: '' };
+  if (secMap) mat.defines = { ...mat.defines, S3M_ATLAS_SEC: '' };
+  // 官方 uTextureDim = (base宽, base高, bake宽, bake高)，取实际绑定纹理的像素尺寸
+  const uAtlasDim = { value: new THREE.Vector2(opts.map?.image?.width || 1, opts.map?.image?.height || 1) };
+  const uAtlasDim1 = { value: new THREE.Vector2(secMap?.image?.width || 1, secMap?.image?.height || 1) };
+
   mat.onBeforeCompile = (shader) => {
     Object.assign(shader.uniforms, uniforms, {
       uSelBatch,
@@ -493,6 +604,9 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
       uBatchTex,
       uBatchTexWidth,
       uBatchTexActive,
+      uSecMap: { value: secMap },
+      uAtlasDim,
+      uAtlasDim1,
     });
 
     shader.vertexShader = shader.vertexShader
@@ -504,10 +618,29 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
       .replace('#include <common>', `#include <common>\n${FRAG_PARS}`)
       .replace('#include <color_fragment>', `#include <color_fragment>\n${FRAG_COLOR}`)
       .replace('#include <emissivemap_fragment>', `#include <emissivemap_fragment>\n${FRAG_EMISSIVE}`);
+
+    if (atlas) {
+      // onBeforeCompile 收到的还是未展开的 `#include <map_fragment>`，不是 include 里的
+      // `texture2D( map, vMapUv )`。只替换后者会静默 no-op，最终仍按整张图集普通采样。
+      const atlasMapFragment = /* glsl */ `
+        #ifdef USE_MAP
+          vec4 sampledDiffuseColor = s3mAtlasUnit( vMapUv, vAtlasRect, uAtlasDim, map );
+          diffuseColor *= sampledDiffuseColor;
+        #endif
+      `;
+      shader.fragmentShader = shader.fragmentShader.replace(
+        '#include <map_fragment>',
+        `${atlasMapFragment}${secMap ? `\n${FRAG_BAKE}` : ''}`
+      );
+    } else if (secMap) {
+      shader.fragmentShader = shader.fragmentShader.replace('#include <map_fragment>', `#include <map_fragment>\n${FRAG_BAKE}`);
+    }
   };
 
-  // 不同材质共用同一段注入代码，必须让 three 认为它们的 program 可复用
-  mat.customProgramCacheKey = () => 's3m-styled';
+  // 不同材质共用同一段注入代码，必须让 three 认为它们的 program 可复用；
+  // 但图集 / 烘焙两套宏会改注入结果，必须进 cacheKey，否则会复用错 program。
+  mat.customProgramCacheKey = () =>
+    `s3m-styled${atlas ? '-atlas' : ''}${secMap ? '-bake' : ''}`;
 
   mat.userData.uSelBatch = uSelBatch;
   mat.userData.uSelWhole = uSelWhole;

package/src/render/TextureFactory.ts

@@ -47,7 +47,7 @@ function configure<T extends THREE.Texture>(tex: T, srgb = true): T {
   tex.magFilter = THREE.LinearFilter;
   tex.minFilter = THREE.LinearMipmapLinearFilter;
   tex.generateMipmaps = true;
-  // 建筑立面大多是斜视角，各向异性过滤对清晰度的提升比提高分辨率更直接
+  // 各向异性过滤对斜视角立面清晰度的提升比提高分辨率更直接
   tex.anisotropy = maxAnisotropy;
   if (srgb) tex.colorSpace = THREE.SRGBColorSpace;
   tex.flipY = false;
@@ -55,13 +55,61 @@ function configure<T extends THREE.Texture>(tex: T, srgb = true): T {
   return tex;
 }
 
+/**
+ * S3MBLOCK 图集专用：关掉 GPU mip。
+ *
+ * 官方 `sampleLod` 是显式 `textureLod(tex, uv, 0.0)`，层级靠「把子区域 rect 平移 +
+ * 内缩」自己算（见 StyleMaterial 的 s3mAtlasUnit）。若让 GPU 对整张图集生成 mip，
+ * 自动选的层级会把相邻子区域混进来，远处就是一糊串色 —— 实测照抄公式但留着 GPU mip
+ * 时，画面反而比不改更糟，就是因为这两个变量叠在一起了。
+ */
+function configureAtlas<T extends THREE.Texture>(tex: T): T {
+  configure(tex);
+  tex.wrapS = THREE.ClampToEdgeWrapping;
+  tex.wrapT = THREE.ClampToEdgeWrapping;
+  tex.minFilter = THREE.LinearFilter;
+  tex.generateMipmaps = false;
+  tex.anisotropy = 1;
+  tex.needsUpdate = true;
+  return tex;
+}
+
+/** 行序翻转（原地）。S3MBLOCK 图集按 GL 方向存储（v=0 在最后一行），解码后要翻一次行 */
+function flipRows(rgba: Uint8Array, width: number, height: number): void {
+  const row = width * 4;
+  const tmp = new Uint8Array(row);
+  for (let y = 0; y < height >> 1; y++) {
+    const a = y * row;
+    const b = (height - 1 - y) * row;
+    tmp.set(rgba.subarray(a, a + row));
+    rgba.copyWithin(a, b, b + row);
+    rgba.set(tmp, b);
+  }
+}
+
+/** 该像素格式自带 alpha 通道（DXT1 的 1bit alpha 不算，历史上没开过 alphaTest） */
+function hasAlphaChannel(pixelFormat: number): boolean {
+  return (
+    pixelFormat === PixelFormat.DXT3 ||
+    pixelFormat === PixelFormat.DXT4 ||
+    pixelFormat === PixelFormat.DXT5 ||
+    pixelFormat === PixelFormat.ARGB ||
+    pixelFormat === PixelFormat.ABGR ||
+    pixelFormat === PixelFormat.BGRA ||
+    pixelFormat === PixelFormat.RGBA
+  );
+}
+
 /** 解 DXT 到 RGBA8。DXT5 是 1 字节/像素，DXT1 是 0.5 字节/像素。 */
 /** DXT 解码只需要尺寸 / 格式 / 字节，CRN 转码出来的结果也走这条路 */
-function decodeDXT(tex: Pick<S3MTexture, 'width' | 'height' | 'pixelFormat' | 'data'>): THREE.DataTexture {
+function decodeDXT(tex: Pick<S3MTexture, 'width' | 'height' | 'pixelFormat' | 'data' | 'flipY'>): THREE.DataTexture {
   const { width, height, pixelFormat, data } = tex;
   const out = new Uint8Array(width * height * 4);
   DXTTextureDecode.decode(out, width, height, data, pixelFormat);
-  return new THREE.DataTexture(out, width, height, THREE.RGBAFormat, THREE.UnsignedByteType);
+  if (tex.flipY) flipRows(out, width, height);
+  const dt = new THREE.DataTexture(out, width, height, THREE.RGBAFormat, THREE.UnsignedByteType);
+  if (hasAlphaChannel(pixelFormat)) dt.userData.s3mHasAlpha = true;
+  return dt;
 }
 
 function fromRawRGB(tex: S3MTexture): THREE.DataTexture {
@@ -83,12 +131,20 @@ function fromRawRGB(tex: S3MTexture): THREE.DataTexture {
     out[d + 2] = swapRB ? data[p] : data[p + 2];
     out[d + 3] = hasAlpha ? data[alphaFirst ? s : s + 3] : 255;
   }
-  return new THREE.DataTexture(out, width, height, THREE.RGBAFormat, THREE.UnsignedByteType);
+  if (tex.flipY) flipRows(out, width, height);
+  const dt = new THREE.DataTexture(out, width, height, THREE.RGBAFormat, THREE.UnsignedByteType);
+  if (hasAlphaChannel(pixelFormat)) dt.userData.s3mHasAlpha = true;
+  return dt;
 }
 
 export async function createTexture(tex: S3MTexture | null | undefined): Promise<DecodedTexture> {
   if (!tex || !tex.width || !tex.height) return { texture: null, decoded: 'empty' };
 
+  // 图集纹理（flipY 的原始 DXT 图集 / AtlasPack 拼出来的 RGBA 大图 / leaf 组合画布）都必须
+  // 关 GPU mip，层级由 StyleMaterial.s3mAtlasUnit 的内联金字塔自己算。
+  const isAtlas = tex.packed === true || tex.flipY === true || tex.composed === true;
+  const asAtlas = <T extends THREE.Texture>(t: T): T => (isAtlas ? configureAtlas(t) : configure(t));
+
   // 判定只能看 compressType：v3.00 的 CRN 纹理 pixelFormat 是 13（ABGR）、
   // 行标的 CRN 是 32856（GL_RGBA8），都不是 26 / 27（见 core/TextureFormat.ts）
   const kind = resolveTextureKind(tex.compressType ?? 0, tex.pixelFormat);
@@ -102,7 +158,7 @@ export async function createTexture(tex: S3MTexture | null | undefined): Promise
         pixelFormat: crn.dxtFormat === 1 ? 17 : 21,
         data: crn.data,
       });
-      return { texture: configure(decoded), decoded: `crn->dxt${crn.dxtFormat}` };
+      return { texture: asAtlas(decoded), decoded: `crn->dxt${crn.dxtFormat}` };
     } catch (e) {
       // 一张纹理坏了不该带崩整个瓦片，如实上报并降级成无贴图
       console.warn('[s3m] CRN 转码失败：', e);
@@ -111,10 +167,9 @@ export async function createTexture(tex: S3MTexture | null | undefined): Promise
   }
 
   if (kind === 'dxt1' || kind === 'dxt3' || kind === 'dxt4' || kind === 'dxt5') {
-    return {
-      texture: configure(decodeDXT({ ...tex, pixelFormat: dxtPixelFormatOf(kind) })),
-      decoded: kind,
-    };
+    const decoded = decodeDXT({ ...tex, pixelFormat: dxtPixelFormatOf(kind) });
+    // flipY 为真即 S3MBLOCK 图集（见 core/types.ts），必须无 mip
+    return { texture: asAtlas(decoded), decoded: kind };
   }
 
   if (kind === 'webp') {
@@ -122,11 +177,12 @@ export async function createTexture(tex: S3MTexture | null | undefined): Promise
     const bmp = await createImageBitmap(blob);
     const t = new THREE.Texture(bmp);
     t.needsUpdate = true;
-    return { texture: configure(t), decoded: 'webp' };
+    return { texture: asAtlas(t), decoded: 'webp' };
   }
 
   if (kind === 'raw') {
-    return { texture: configure(fromRawRGB(tex)), decoded: 'raw' };
+    const decoded = fromRawRGB(tex);
+    return { texture: asAtlas(decoded), decoded: 'raw' };
   }
 
   // KTX2 / ETC 需要额外解码器，先如实上报而不是静默出错