@takram/three-geospatial 0.0.1-alpha.6 → 0.0.1-alpha.7

package/src/defineShorthand.ts

@@ -0,0 +1,68 @@
+import { type Uniform } from 'three'
+
+// TODO: Make mutable value types (e.g. vectors, matrices) read-only.
+
+// Maps argument of type [T1, K1[], T2, K2[], ...] to:
+// { [K in K1]: T1[K],
+//   [K in K2]: T2[K], ... }
+export type PropertyShorthand<Args extends readonly unknown[]> =
+  Args extends readonly [infer T, infer K, ...infer Rest]
+    ? K extends readonly string[]
+      ? K[number] extends keyof T
+        ? Rest extends readonly unknown[]
+          ? { [P in K[number]]: T[P] } & PropertyShorthand<Rest>
+          : { [P in K[number]]: T[P] }
+        : never // K must be keyof T
+      : never // K must be an array
+    : {} // Termination
+
+export function definePropertyShorthand<T, Args extends readonly unknown[]>(
+  destination: T,
+  ...sourceKeysArgs: [...Args]
+): T & PropertyShorthand<Args> {
+  const descriptors: PropertyDescriptorMap = {}
+  for (let i = 0; i < sourceKeysArgs.length; i += 2) {
+    const source = sourceKeysArgs[i]
+    const keys = sourceKeysArgs[i + 1] as ReadonlyArray<keyof typeof source>
+    for (const key of keys) {
+      descriptors[key] = {
+        enumerable: true,
+        get: () => source[key],
+        set: (value: any) => {
+          source[key] = value
+        }
+      }
+    }
+  }
+  Object.defineProperties(destination, descriptors)
+  return destination as T & PropertyShorthand<Args>
+}
+
+// The argument of defineUniformShorthand can also be variadic, but I can't
+// think of any practical use cases for it.
+
+export type UniformShorthand<
+  T extends { uniforms: Record<K, Uniform> },
+  K extends keyof T['uniforms']
+> = {
+  [P in K]: T['uniforms'][P] extends Uniform<infer U> ? U : never
+}
+
+export function defineUniformShorthand<
+  T,
+  S extends { uniforms: Record<K, Uniform> },
+  K extends keyof S['uniforms']
+>(destination: T, source: S, keys: readonly K[]): T & UniformShorthand<S, K> {
+  const descriptors: PropertyDescriptorMap = {}
+  for (const key of keys) {
+    descriptors[key] = {
+      enumerable: true,
+      get: () => source.uniforms[key].value,
+      set: (value: S['uniforms'][K]) => {
+        source.uniforms[key].value = value
+      }
+    }
+  }
+  Object.defineProperties(destination, descriptors)
+  return destination as T & UniformShorthand<S, K>
+}

package/src/index.ts

@@ -3,6 +3,7 @@ export * from './assertions'
 export * from './bufferGeometry'
 export * from './constants'
 export * from './DataLoader'
+export * from './defineShorthand'
 export * from './Ellipsoid'
 export * from './EllipsoidGeometry'
 export * from './Geodetic'
@@ -10,6 +11,7 @@ export * from './math'
 export * from './PointOfView'
 export * from './Rectangle'
 export * from './resolveIncludes'
+export * from './STBNLoader'
 export * from './TileCoordinate'
 export * from './TilingScheme'
 export * from './typedArray'

package/src/math.ts

@@ -10,7 +10,42 @@ export const isPowerOfTwo = MathUtils.isPowerOfTwo
 export const ceilPowerOfTwo = MathUtils.ceilPowerOfTwo
 export const floorPowerOfTwo = MathUtils.floorPowerOfTwo
 export const normalize = MathUtils.normalize
-export const remap = MathUtils.mapLinear
+
+export function remap(x: number, min1: number, max1: number): number
+export function remap(
+  x: number,
+  min1: number,
+  max1: number,
+  min2: number,
+  max2: number
+): number
+export function remap(
+  x: number,
+  min1: number,
+  max1: number,
+  min2 = 0,
+  max2 = 1
+): number {
+  return MathUtils.mapLinear(x, min1, max1, min2, max2)
+}
+
+export function remapClamped(x: number, min1: number, max1: number): number
+export function remapClamped(
+  x: number,
+  min1: number,
+  max1: number,
+  min2: number,
+  max2: number
+): number
+export function remapClamped(
+  x: number,
+  min1: number,
+  max1: number,
+  min2 = 0,
+  max2 = 1
+): number {
+  return clamp(MathUtils.mapLinear(x, min1, max1, min2, max2), min2, max2)
+}
 
 // Prefer glsl's argument order which differs from that of MathUtils.
 export function smoothstep(min: number, max: number, x: number): number {

package/src/r3f/types.ts

@@ -1,13 +1,13 @@
 import {
-  type Color,
-  type ExtendedColors,
   type NodeProps,
   type Overwrite,
-  type Vector2,
-  type Vector3,
-  type Vector4
+  type Color as R3FColor,
+  type Vector2 as R3FVector2,
+  type Vector3 as R3FVector3,
+  type Vector4 as R3FVector4
 } from '@react-three/fiber'
 import {
+  type Color as ColorImpl,
   type Vector2 as Vector2Impl,
   type Vector3 as Vector3Impl,
   type Vector4 as Vector4Impl
@@ -17,16 +17,15 @@ import { type WritableKeysOf } from 'type-fest'
 import { type Callable } from '../types'
 
 // prettier-ignore
-export type ExtendedVectors<T> = {
+export type ExtendedProps<T> = {
   [K in keyof T]:
-    Vector2Impl extends T[K] ? Vector2 | T[K] :
-    Vector3Impl extends T[K] ? Vector3 | T[K] :
-    Vector4Impl extends T[K] ? Vector4 | T[K] :
+    Vector2Impl extends T[K] ? R3FVector2 | T[K] :
+    Vector3Impl extends T[K] ? R3FVector3 | T[K] :
+    Vector4Impl extends T[K] ? R3FVector4 | T[K] :
+    ColorImpl extends T[K] ? R3FColor | T[K] :
     T[K]
 }
 
-export type ExtendedProps<T> = ExtendedColors<ExtendedVectors<T>>
-
 // @react-three/fiber's NonFunctionKeys cannot exclude partial functions.
 // This excludes callback properties, which may be undesirable behavior.
 type NonFunctionKeys<T> = keyof {
@@ -41,7 +40,7 @@ type WritableNonExtendableKeysOf<T> =
         Vector2Impl extends T[K] ? K :
         Vector3Impl extends T[K] ? K :
         Vector4Impl extends T[K] ? K :
-        Color extends T[K] ? K :
+        ColorImpl extends T[K] ? K :
         never
       ]: any
     }

package/src/shaders/cascadedShadowMaps.glsl

@@ -0,0 +1,79 @@
+// Reference: https://github.com/mrdoob/three.js/blob/r171/examples/jsm/csm/CSMShader.js
+
+#ifndef SHADOW_CASCADE_COUNT
+#error "SHADOW_CASCADE_COUNT macro must be defined."
+#endif // SHADOW_CASCADE_COUNT
+
+int getCascadeIndex(
+  const mat4 viewMatrix,
+  const vec3 worldPosition,
+  const vec2 intervals[SHADOW_CASCADE_COUNT],
+  const float near,
+  const float far
+) {
+  vec4 viewPosition = viewMatrix * vec4(worldPosition, 1.0);
+  float depth = viewZToOrthographicDepth(viewPosition.z, near, far);
+  vec2 interval;
+  #pragma unroll_loop_start
+  for (int i = 0; i < 4; ++i) {
+    #if UNROLLED_LOOP_INDEX < SHADOW_CASCADE_COUNT
+    interval = intervals[i];
+    if (depth >= interval.x && depth < interval.y) {
+      return UNROLLED_LOOP_INDEX;
+    }
+    #endif // UNROLLED_LOOP_INDEX < SHADOW_CASCADE_COUNT
+  }
+  #pragma unroll_loop_end
+  return SHADOW_CASCADE_COUNT - 1;
+}
+
+int getFadedCascadeIndex(
+  const mat4 viewMatrix,
+  const vec3 worldPosition,
+  const vec2 intervals[SHADOW_CASCADE_COUNT],
+  const float near,
+  const float far,
+  const float jitter
+) {
+  vec4 viewPosition = viewMatrix * vec4(worldPosition, 1.0);
+  float depth = viewZToOrthographicDepth(viewPosition.z, near, far);
+
+  vec2 interval;
+  float intervalCenter;
+  float closestEdge;
+  float margin;
+  int nextIndex = -1;
+  int prevIndex = -1;
+  float alpha;
+
+  #pragma unroll_loop_start
+  for (int i = 0; i < 4; ++i) {
+    #if UNROLLED_LOOP_INDEX < SHADOW_CASCADE_COUNT
+    interval = intervals[i];
+    intervalCenter = (interval.x + interval.y) * 0.5;
+    closestEdge = depth < intervalCenter ? interval.x : interval.y;
+    margin = closestEdge * closestEdge * 0.5;
+    interval += margin * vec2(-0.5, 0.5);
+
+    #if UNROLLED_LOOP_INDEX < SHADOW_CASCADE_COUNT - 1
+    if (depth >= interval.x && depth < interval.y) {
+      prevIndex = nextIndex;
+      nextIndex = UNROLLED_LOOP_INDEX;
+      alpha = saturate(min(depth - interval.x, interval.y - depth) / margin);
+    }
+    #else // UNROLLED_LOOP_INDEX < SHADOW_CASCADE_COUNT - 1
+    // Don't fade out the last cascade.
+    if (depth >= interval.x) {
+      prevIndex = nextIndex;
+      nextIndex = UNROLLED_LOOP_INDEX;
+      alpha = saturate((depth - interval.x) / margin);
+    }
+    #endif // UNROLLED_LOOP_INDEX < SHADOW_CASCADE_COUNT - 1
+    #endif // UNROLLED_LOOP_INDEX < SHADOW_CASCADE_COUNT
+  }
+  #pragma unroll_loop_end
+
+  return jitter <= alpha
+    ? nextIndex
+    : prevIndex;
+}

package/src/shaders/index.ts

@@ -1,3 +1,4 @@
+import _cascadedShadowMaps from './cascadedShadowMaps.glsl?raw'
 import _depth from './depth.glsl?raw'
 import _generators from './generators.glsl?raw'
 import _math from './math.glsl?raw'
@@ -7,6 +8,7 @@ import _raySphereIntersection from './raySphereIntersection.glsl?raw'
 import _transform from './transform.glsl?raw'
 import _turbo from './turbo.glsl?raw'
 
+export const cascadedShadowMaps: string = _cascadedShadowMaps
 export const depth: string = _depth
 export const generators: string = _generators
 export const math: string = _math

package/src/shaders/math.glsl

@@ -2,22 +2,6 @@
 #define saturate(a) clamp(a, 0.0, 1.0)
 #endif // !defined(saturate)
 
-float inverseLerp(const float x, const float y, const float a) {
-  return (a - x) / (y - x);
-}
-
-vec2 inverseLerp(const vec2 x, const vec2 y, const vec2 a) {
-  return (a - x) / (y - x);
-}
-
-vec3 inverseLerp(const vec3 x, const vec3 y, const vec3 a) {
-  return (a - x) / (y - x);
-}
-
-vec4 inverseLerp(const vec4 x, const vec4 y, const vec4 a) {
-  return (a - x) / (y - x);
-}
-
 float remap(const float x, const float min1, const float max1, const float min2, const float max2) {
   return min2 + (x - min1) / (max1 - min1) * (max2 - min2);
 }
@@ -34,6 +18,46 @@ vec4 remap(const vec4 x, const vec4 min1, const vec4 max1, const vec4 min2, cons
   return min2 + (x - min1) / (max1 - min1) * (max2 - min2);
 }
 
+float remapClamped(
+  const float x,
+  const float min1,
+  const float max1,
+  const float min2,
+  const float max2
+) {
+  return clamp(min2 + (x - min1) / (max1 - min1) * (max2 - min2), min2, max2);
+}
+
+vec2 remapClamped(
+  const vec2 x,
+  const vec2 min1,
+  const vec2 max1,
+  const vec2 min2,
+  const vec2 max2
+) {
+  return clamp(min2 + (x - min1) / (max1 - min1) * (max2 - min2), min2, max2);
+}
+
+vec3 remapClamped(
+  const vec3 x,
+  const vec3 min1,
+  const vec3 max1,
+  const vec3 min2,
+  const vec3 max2
+) {
+  return clamp(min2 + (x - min1) / (max1 - min1) * (max2 - min2), min2, max2);
+}
+
+vec4 remapClamped(
+  const vec4 x,
+  const vec4 min1,
+  const vec4 max1,
+  const vec4 min2,
+  const vec4 max2
+) {
+  return clamp(min2 + (x - min1) / (max1 - min1) * (max2 - min2), min2, max2);
+}
+
 // Implicitly remap to 0 and 1
 float remap(const float x, const float min1, const float max1) {
   return (x - min1) / (max1 - min1);
@@ -50,3 +74,19 @@ vec3 remap(const vec3 x, const vec3 min1, const vec3 max1) {
 vec4 remap(const vec4 x, const vec4 min1, const vec4 max1) {
   return (x - min1) / (max1 - min1);
 }
+
+float remapClamped(const float x, const float min1, const float max1) {
+  return saturate((x - min1) / (max1 - min1));
+}
+
+vec2 remapClamped(const vec2 x, const vec2 min1, const vec2 max1) {
+  return saturate((x - min1) / (max1 - min1));
+}
+
+vec3 remapClamped(const vec3 x, const vec3 min1, const vec3 max1) {
+  return saturate((x - min1) / (max1 - min1));
+}
+
+vec4 remapClamped(const vec4 x, const vec4 min1, const vec4 max1) {
+  return saturate((x - min1) / (max1 - min1));
+}

package/src/shaders/poissonDisk.glsl

@@ -1,3 +1,5 @@
+// TODO: Maybe switch to Vogel disk with IGN:
+// https://www.gamedev.net/tutorials/programming/graphics/contact-hardening-soft-shadows-made-fast-r4906/
 // Taken from: https://developer.download.nvidia.com/whitepapers/2008/PCSS_Integration.pdf
 const vec2 poissonDisk[16] = vec2[16](
   vec2(-0.94201624, -0.39906216),

package/src/typedArrayParsers.ts

@@ -1,5 +1,17 @@
 import { type TypedArray, type TypedArrayConstructor } from './typedArray'
 
+let hostLittleEndian: boolean | undefined
+
+function isHostLittleEndian(): boolean {
+  if (hostLittleEndian != null) {
+    return hostLittleEndian
+  }
+  const a = new Uint32Array([0x10000000])
+  const b = new Uint8Array(a.buffer, a.byteOffset, a.byteLength)
+  hostLittleEndian = b[0] === 0
+  return hostLittleEndian
+}
+
 type GetValue = keyof {
   [K in keyof DataView as DataView[K] extends (byteOffset: number) => number
     ? K
@@ -19,6 +31,9 @@ function parseTypedArray<K extends GetValue>(
   getValue: K,
   littleEndian = true
 ): TypedArray {
+  if (littleEndian === isHostLittleEndian()) {
+    return new TypedArray(buffer)
+  }
   const data = new DataView(buffer)
   const array = new TypedArray(data.byteLength / TypedArray.BYTES_PER_ELEMENT)
   for (
@@ -36,15 +51,11 @@ export type TypedArrayParser<T extends TypedArray> = (
   littleEndian?: boolean
 ) => T
 
-export const parseUint8Array: TypedArrayParser<Uint8Array> = (
-  buffer,
-  littleEndian
-) => parseTypedArray(buffer, Uint8Array, 'getUint8', littleEndian)
+export const parseUint8Array: TypedArrayParser<Uint8Array> = buffer =>
+  new Uint8Array(buffer)
 
-export const parseInt8Array: TypedArrayParser<Int8Array> = (
-  buffer,
-  littleEndian
-) => parseTypedArray(buffer, Int8Array, 'getInt8', littleEndian)
+export const parseInt8Array: TypedArrayParser<Int8Array> = buffer =>
+  new Int8Array(buffer)
 
 export const parseUint16Array: TypedArrayParser<Uint16Array> = (
   buffer,

package/types/STBNLoader.d.ts

@@ -0,0 +1 @@
+export declare const STBNLoader: import('type-fest').Class<import('./DataLoader').DataLoader<import('three').Data3DTexture, Uint8Array<ArrayBufferLike>>>;

package/types/constants.d.ts

@@ -1,3 +1,4 @@
 export declare const STBN_TEXTURE_WIDTH = 128;
 export declare const STBN_TEXTURE_HEIGHT = 128;
 export declare const STBN_TEXTURE_DEPTH = 64;
+export declare const DEFAULT_STBN_URL = "https://media.githubusercontent.com/media/takram-design-engineering/three-geospatial/9627216cc50057994c98a2118f3c4a23765d43b9/packages/core/assets/stbn.bin";

package/types/defineShorthand.d.ts

@@ -0,0 +1,16 @@
+import { Uniform } from 'three';
+
+export type PropertyShorthand<Args extends readonly unknown[]> = Args extends readonly [infer T, infer K, ...infer Rest] ? K extends readonly string[] ? K[number] extends keyof T ? Rest extends readonly unknown[] ? {
+    [P in K[number]]: T[P];
+} & PropertyShorthand<Rest> : {
+    [P in K[number]]: T[P];
+} : never : never : {};
+export declare function definePropertyShorthand<T, Args extends readonly unknown[]>(destination: T, ...sourceKeysArgs: [...Args]): T & PropertyShorthand<Args>;
+export type UniformShorthand<T extends {
+    uniforms: Record<K, Uniform>;
+}, K extends keyof T['uniforms']> = {
+    [P in K]: T['uniforms'][P] extends Uniform<infer U> ? U : never;
+};
+export declare function defineUniformShorthand<T, S extends {
+    uniforms: Record<K, Uniform>;
+}, K extends keyof S['uniforms']>(destination: T, source: S, keys: readonly K[]): T & UniformShorthand<S, K>;

package/types/index.d.ts

@@ -3,6 +3,7 @@ export * from './assertions';
 export * from './bufferGeometry';
 export * from './constants';
 export * from './DataLoader';
+export * from './defineShorthand';
 export * from './Ellipsoid';
 export * from './EllipsoidGeometry';
 export * from './Geodetic';
@@ -10,6 +11,7 @@ export * from './math';
 export * from './PointOfView';
 export * from './Rectangle';
 export * from './resolveIncludes';
+export * from './STBNLoader';
 export * from './TileCoordinate';
 export * from './TilingScheme';
 export * from './typedArray';

package/types/math.d.ts

@@ -8,7 +8,10 @@ export declare const isPowerOfTwo: typeof import('three/src/math/MathUtils.js').
 export declare const ceilPowerOfTwo: typeof import('three/src/math/MathUtils.js').ceilPowerOfTwo;
 export declare const floorPowerOfTwo: typeof import('three/src/math/MathUtils.js').floorPowerOfTwo;
 export declare const normalize: typeof import('three/src/math/MathUtils.js').normalize;
-export declare const remap: typeof import('three/src/math/MathUtils.js').mapLinear;
+export declare function remap(x: number, min1: number, max1: number): number;
+export declare function remap(x: number, min1: number, max1: number, min2: number, max2: number): number;
+export declare function remapClamped(x: number, min1: number, max1: number): number;
+export declare function remapClamped(x: number, min1: number, max1: number, min2: number, max2: number): number;
 export declare function smoothstep(min: number, max: number, x: number): number;
 export declare function saturate(x: number): number;
 export declare function closeTo(a: number, b: number, relativeEpsilon: number, absoluteEpsilon?: number): boolean;

package/types/r3f/types.d.ts

@@ -1,17 +1,16 @@
 import { Callable } from '../types';
 import { WritableKeysOf } from 'type-fest';
-import { Vector2 as Vector2Impl, Vector3 as Vector3Impl, Vector4 as Vector4Impl } from 'three';
-import { Color, ExtendedColors, NodeProps, Overwrite, Vector2, Vector3, Vector4 } from '@react-three/fiber';
+import { Color as ColorImpl, Vector2 as Vector2Impl, Vector3 as Vector3Impl, Vector4 as Vector4Impl } from 'three';
+import { NodeProps, Overwrite, Color as R3FColor, Vector2 as R3FVector2, Vector3 as R3FVector3, Vector4 as R3FVector4 } from '@react-three/fiber';
 
-export type ExtendedVectors<T> = {
-    [K in keyof T]: Vector2Impl extends T[K] ? Vector2 | T[K] : Vector3Impl extends T[K] ? Vector3 | T[K] : Vector4Impl extends T[K] ? Vector4 | T[K] : T[K];
+export type ExtendedProps<T> = {
+    [K in keyof T]: Vector2Impl extends T[K] ? R3FVector2 | T[K] : Vector3Impl extends T[K] ? R3FVector3 | T[K] : Vector4Impl extends T[K] ? R3FVector4 | T[K] : ColorImpl extends T[K] ? R3FColor | T[K] : T[K];
 };
-export type ExtendedProps<T> = ExtendedColors<ExtendedVectors<T>>;
 type NonFunctionKeys<T> = keyof {
     [K in keyof T as Callable extends T[K] ? never : K]: any;
 };
 type WritableNonExtendableKeysOf<T> = WritableKeysOf<T> | keyof {
-    [K in keyof T as Vector2Impl extends T[K] ? K : Vector3Impl extends T[K] ? K : Vector4Impl extends T[K] ? K : Color extends T[K] ? K : never]: any;
+    [K in keyof T as Vector2Impl extends T[K] ? K : Vector3Impl extends T[K] ? K : Vector4Impl extends T[K] ? K : ColorImpl extends T[K] ? K : never]: any;
 };
 export type PassThoughInstanceProps<RefType, Args extends readonly any[], Props> = Overwrite<ExtendedProps<{
     [K in NonFunctionKeys<Props> as K extends WritableNonExtendableKeysOf<Props> ? K : never]: Props[K];

package/types/shaders/index.d.ts

@@ -1,3 +1,4 @@
+export declare const cascadedShadowMaps: string;
 export declare const depth: string;
 export declare const generators: string;
 export declare const math: string;