@viggle/splat-engine-three 0.1.1 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +58 -0
- package/README.md +158 -20
- package/dist/chunks/chunk-2GKWT24B.js +23182 -0
- package/dist/chunks/chunk-2GKWT24B.js.map +7 -0
- package/dist/index.js +235 -3
- package/dist/types/anim/animation-conversion.d.ts +2 -2
- package/dist/types/anim/keyframe-splines.d.ts +17 -41
- package/dist/types/animation.d.ts +84 -28
- package/dist/types/armature.d.ts +280 -2
- package/dist/types/character.d.ts +120 -2
- package/dist/types/effects/index.d.ts +12 -0
- package/dist/types/effects/outlines/outline-effect.d.ts +98 -0
- package/dist/types/effects/outlines/outline-shaders.d.ts +14 -0
- package/dist/types/effects/pixelart/pixelart-effect.d.ts +152 -0
- package/dist/types/effects/pixelart/pixelart-shaders.d.ts +31 -0
- package/dist/types/effects/postfx/base-capturing-pass.d.ts +109 -0
- package/dist/types/effects/postfx/camera-frame.d.ts +103 -0
- package/dist/types/effects/postfx/frame-renderer.d.ts +32 -0
- package/dist/types/effects/postfx/frame-shaders.d.ts +19 -0
- package/dist/types/effects/postfx/mask.d.ts +44 -0
- package/dist/types/effects/postfx/postfx.d.ts +144 -0
- package/dist/types/effects/postfx/program.d.ts +74 -0
- package/dist/types/effects/postfx/uniforms.d.ts +24 -0
- package/dist/types/effects/postfx/webgl-program.d.ts +6 -0
- package/dist/types/effects/postfx/webgpu-program.d.ts +3 -0
- package/dist/types/effects/vfx/data-types.d.ts +100 -0
- package/dist/types/effects/vfx/index.d.ts +37 -0
- package/dist/types/effects/vfx/json-vfx-prefab.d.ts +94 -0
- package/dist/types/effects/vfx/layer-renderer.d.ts +118 -0
- package/dist/types/effects/vfx/layers/mesh.d.ts +124 -0
- package/dist/types/effects/vfx/layers/particle.d.ts +90 -0
- package/dist/types/effects/vfx/layers/shader.d.ts +130 -0
- package/dist/types/effects/vfx/layers/shared.d.ts +40 -0
- package/dist/types/effects/vfx/layers/sprite.d.ts +45 -0
- package/dist/types/effects/vfx/pool.d.ts +51 -0
- package/dist/types/effects/vfx/prefab.d.ts +48 -0
- package/dist/types/effects/vfx/prewarm.d.ts +17 -0
- package/dist/types/effects/vfx/stage.d.ts +115 -0
- package/dist/types/effects/vfx/webgpu-register.d.ts +2 -0
- package/dist/types/effects/webgpu-register.d.ts +2 -0
- package/dist/types/engine.d.ts +18 -0
- package/dist/types/environment.d.ts +96 -8
- package/dist/types/index.d.ts +35 -6
- package/dist/types/loader/animation/animation-glb.d.ts +4 -4
- package/dist/types/loader/character/load.d.ts +6 -1
- package/dist/types/loader/environment/lod-bundle.d.ts +123 -0
- package/dist/types/loader/environment/spz-decode.d.ts +88 -0
- package/dist/types/loader/environment/spz.d.ts +28 -0
- package/dist/types/loader/shared/asset-fetch.d.ts +11 -0
- package/dist/types/loader/shared/asset-loader.d.ts +86 -0
- package/dist/types/loader/shared/bin-cache.d.ts +41 -14
- package/dist/types/loader/shared/decode-worker.d.ts +27 -0
- package/dist/types/loader/shared/glb.d.ts +30 -0
- package/dist/types/loader/shared/inflate.d.ts +9 -0
- package/dist/types/loader/shared/pack-splats-task.d.ts +17 -0
- package/dist/types/loader/shared/sog-decode.d.ts +81 -0
- package/dist/types/loader/shared/sog.d.ts +17 -0
- package/dist/types/math.d.ts +198 -13
- package/dist/types/physics/ammo.d.ts +217 -0
- package/dist/types/physics/index.d.ts +11 -0
- package/dist/types/physics/joints.d.ts +206 -0
- package/dist/types/physics/physics-world.d.ts +194 -0
- package/dist/types/physics/rigid-body.d.ts +361 -0
- package/dist/types/presets/camera/camera-preset.d.ts +43 -0
- package/dist/types/presets/camera/third-person-camera.d.ts +63 -0
- package/dist/types/presets/character/body-shape.d.ts +109 -0
- package/dist/types/presets/character/character-reveal.d.ts +90 -0
- package/dist/types/presets/character/socket-loadout.d.ts +61 -0
- package/dist/types/presets/index.d.ts +13 -0
- package/dist/types/presets/vfx/mesh-flash.d.ts +51 -0
- package/dist/types/presets/visual/bone-overlay.d.ts +57 -0
- package/dist/types/proxy/environment-input.d.ts +30 -0
- package/dist/types/proxy/environment-source.d.ts +39 -0
- package/dist/types/proxy/proxy-debug.d.ts +106 -0
- package/dist/types/proxy/splat-source.d.ts +42 -0
- package/dist/types/proxy/voxelizer.d.ts +383 -0
- package/dist/types/relight/backend.d.ts +101 -0
- package/dist/types/relight/index.d.ts +6 -0
- package/dist/types/relight/relight-pass.d.ts +367 -0
- package/dist/types/relight/relight-placeholder.d.ts +2 -0
- package/dist/types/relight/relight-shaders.d.ts +4 -0
- package/dist/types/relight/shadow-bias.d.ts +26 -0
- package/dist/types/relight/splat-relight.d.ts +760 -0
- package/dist/types/relight/webgl-backend.d.ts +3 -0
- package/dist/types/relight/webgpu/backend.d.ts +3 -0
- package/dist/types/relight/webgpu-register.d.ts +2 -0
- package/dist/types/scene.d.ts +291 -0
- package/dist/types/skeletal/animation-player.d.ts +31 -3
- package/dist/types/skeletal/body-parts.d.ts +55 -0
- package/dist/types/skeletal/ragdoll-config.d.ts +115 -0
- package/dist/types/skeletal/ragdoll.d.ts +283 -0
- package/dist/types/skeletal/skeleton.d.ts +9 -2
- package/dist/types/splat/backend.d.ts +2 -0
- package/dist/types/splat/color-modifier.d.ts +78 -0
- package/dist/types/splat/cut-groups.d.ts +27 -0
- package/dist/types/splat/relight-binding.d.ts +39 -0
- package/dist/types/splat/reveal-bake.d.ts +43 -0
- package/dist/types/splat/reveal-look.d.ts +64 -0
- package/dist/types/splat/splat-mesh.d.ts +1 -0
- package/dist/types/splat/splat.d.ts +154 -0
- package/dist/types/splat/webgl/shaders.d.ts +5 -1
- package/dist/types/splat/webgl/splat-mesh.d.ts +4 -0
- package/dist/types/splat/webgpu/radix-sort.d.ts +3 -0
- package/dist/types/splat/webgpu/splat-mesh.d.ts +23 -0
- package/dist/types/three/splat-character.d.ts +28 -0
- package/dist/types/three/spz-loader.d.ts +35 -0
- package/dist/types/types.d.ts +6 -0
- package/dist/webgpu.js +1137 -154
- package/dist/webgpu.js.map +4 -4
- package/package.json +6 -2
- package/dist/chunks/chunk-WN5WBKM4.js +0 -8606
- package/dist/chunks/chunk-WN5WBKM4.js.map +0 -7
|
@@ -1,19 +1,46 @@
|
|
|
1
|
+
declare function cacheKeyFor(url: string): string;
|
|
1
2
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
*
|
|
10
|
-
*
|
|
3
|
+
* Delete expired entries and index the rest, so {@link cachedFetch} can start
|
|
4
|
+
* an uncached download without waiting on a Cache API lookup. Call once when
|
|
5
|
+
* the page is idle, before the first load; later calls share the first run.
|
|
6
|
+
* Resolves to the number of entries removed.
|
|
7
|
+
*/
|
|
8
|
+
declare function indexAssetCache(): Promise<number>;
|
|
9
|
+
/**
|
|
10
|
+
* The fetch the engine downloads asset bytes with (`.bin` / `.vsplat`
|
|
11
|
+
* bundles, `.spz` / `.ply` splats, VFX sprite sheets). By default it is the
|
|
12
|
+
* engine's persistent Cache API layer (`engineCachedFetch` above); a host that
|
|
13
|
+
* installs its own with {@link setBinFetch} gets that instead.
|
|
11
14
|
*/
|
|
12
15
|
declare function cachedFetch(url: string, init?: RequestInit): Promise<Response>;
|
|
13
16
|
/**
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
+
* Install the fetch the engine uses for asset bytes, in place of its own
|
|
18
|
+
* Cache API layer: for a host with its own caching stack. Call once at boot, before any asset loads. Pass `null`
|
|
19
|
+
* to go back to the engine's own.
|
|
20
|
+
*/
|
|
21
|
+
declare function setBinFetch(fetchImpl: ((url: string) => Promise<Response>) | null): void;
|
|
22
|
+
/**
|
|
23
|
+
* Route every cacheable asset request made with `fetch` or `XMLHttpRequest`,
|
|
24
|
+
* including PlayCanvas's own (LOD octree chunks, textures, GLBs), through the
|
|
25
|
+
* persistent Cache API layer. Opt-in and global: it replaces
|
|
26
|
+
* `globalThis.fetch` and patches `XMLHttpRequest`. Requests for other URLs
|
|
27
|
+
* pass through untouched. A routed request keeps its headers, credentials
|
|
28
|
+
* mode and abort signal. Call once at boot; safe to call again.
|
|
29
|
+
* {@link uninstallFetchInterceptor} puts both back.
|
|
30
|
+
*/
|
|
31
|
+
declare function installFetchInterceptor(): void;
|
|
32
|
+
/** Undo {@link installFetchInterceptor}: restore `fetch` and `XMLHttpRequest`. No-op when not installed. */
|
|
33
|
+
declare function uninstallFetchInterceptor(): void;
|
|
34
|
+
/**
|
|
35
|
+
* Whether a URL is in the persistent cache (and not expired), without
|
|
36
|
+
* fetching it. False for URLs the cache never stores, or with no Cache API.
|
|
37
|
+
*/
|
|
38
|
+
declare function isCached(url: string): Promise<boolean>;
|
|
39
|
+
/**
|
|
40
|
+
* Former name of {@link indexAssetCache}, kept for compatibility: it
|
|
41
|
+
* still deletes expired entries and resolves to how many it removed.
|
|
42
|
+
*
|
|
43
|
+
* @deprecated Use {@link indexAssetCache}.
|
|
17
44
|
*/
|
|
18
|
-
declare
|
|
19
|
-
export { cachedFetch, evictExpired };
|
|
45
|
+
declare const evictExpired: typeof indexAssetCache;
|
|
46
|
+
export { cacheKeyFor, cachedFetch, evictExpired, indexAssetCache, installFetchInterceptor, isCached, setBinFetch, uninstallFetchInterceptor, };
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One worker, shared by every load, for the CPU-heavy half of an `.spz` or
|
|
3
|
+
* SOG decode, packing included: a million-splat unpack, Morton order and pack
|
|
4
|
+
* is the better part of a second of main thread on a phone otherwise.
|
|
5
|
+
*
|
|
6
|
+
* The worker is built from a Blob of the decode functions' own source text, as
|
|
7
|
+
* `AsyncDepthSorter` builds its sorter, so there is no second file for an
|
|
8
|
+
* application's bundler to lose. Each function is emitted under the name it
|
|
9
|
+
* has in this bundle, which is the name its callers use too - so whatever a
|
|
10
|
+
* bundler or minifier renamed, the functions still find each other.
|
|
11
|
+
*/
|
|
12
|
+
import type { PackedSplats } from '../../splat/packed-splats';
|
|
13
|
+
import { decodeSpzTask } from '../environment/spz-decode';
|
|
14
|
+
import { decodeSogTask } from './sog-decode';
|
|
15
|
+
/** The decode tasks, by name, and what each takes. */
|
|
16
|
+
interface TaskInputs {
|
|
17
|
+
spz: Parameters<typeof decodeSpzTask>[0];
|
|
18
|
+
sog: Parameters<typeof decodeSogTask>[0];
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Decode and pack in the shared worker - or on this thread where there are
|
|
22
|
+
* no workers (a test runner, a server render, a page whose CSP blocks them).
|
|
23
|
+
* The buffers in `transfer` are moved, not copied: the caller must not read
|
|
24
|
+
* them afterwards.
|
|
25
|
+
*/
|
|
26
|
+
export declare function runDecodeTask<K extends keyof TaskInputs>(task: K, input: TaskInputs[K], transfer: ArrayBuffer[]): Promise<PackedSplats>;
|
|
27
|
+
export {};
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import type { GLTF, GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
|
|
2
|
+
/**
|
|
3
|
+
* Use `loader` for {@link loadGlbFromUrl} - one configured with a
|
|
4
|
+
* `DRACOLoader`, `KTX2Loader` or `MeshoptDecoder` for GLBs that need them.
|
|
5
|
+
*
|
|
6
|
+
* @group Loaders
|
|
7
|
+
*/
|
|
8
|
+
export declare function setGlbLoader(loader: GLTFLoader): void;
|
|
9
|
+
/** Callback form of {@link loadGlbFromUrl}: `(error message, null)` or `(null, gltf)`. */
|
|
10
|
+
export type GlbCallback = (err: string | null, gltf: GLTF | null) => void;
|
|
11
|
+
/**
|
|
12
|
+
* Load a `.glb` through the engine's asset cache (so it is served from the
|
|
13
|
+
* persistent cache like characters and clips) and parse it with three.js's
|
|
14
|
+
* `GLTFLoader`. Add `gltf.scene` to your scene, or clone it per use.
|
|
15
|
+
*
|
|
16
|
+
* The PlayCanvas build's `loadGlbFromUrl(app, url, callback)` handed back a
|
|
17
|
+
* container asset; this resolves the parsed `GLTF`. That call shape still
|
|
18
|
+
* works - the leading argument is accepted and not needed - and so does the
|
|
19
|
+
* callback, alongside the returned promise.
|
|
20
|
+
*
|
|
21
|
+
* @example
|
|
22
|
+
* ```ts
|
|
23
|
+
* const gltf = await loadGlbFromUrl('/assets/sword.glb');
|
|
24
|
+
* character.object3D.add(gltf.scene);
|
|
25
|
+
* ```
|
|
26
|
+
*
|
|
27
|
+
* @group Loaders
|
|
28
|
+
*/
|
|
29
|
+
export declare function loadGlbFromUrl(url: string, callback?: GlbCallback): Promise<GLTF>;
|
|
30
|
+
export declare function loadGlbFromUrl(host: unknown, url: string, callback?: GlbCallback): Promise<GLTF>;
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Inflate `data`, refusing to produce more than `maxBytes`. A size the file
|
|
3
|
+
* declares is only an upper bound a hostile one sets itself, so callers cap
|
|
4
|
+
* it by what a valid file could hold; `capFromHead`, when given, tightens the
|
|
5
|
+
* cap once the first `headBytes` of output are in - a format whose header
|
|
6
|
+
* says how long the rest is. Runs in the decode worker too (see
|
|
7
|
+
* `decode-worker.ts`), so it uses nothing from outside itself.
|
|
8
|
+
*/
|
|
9
|
+
export declare function inflateCapped(data: Uint8Array, format: 'gzip' | 'deflate-raw', maxBytes: number, headBytes?: number, capFromHead?: ((head: Uint8Array) => number) | null): Promise<Uint8Array>;
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `packSplats` for the decode worker.
|
|
3
|
+
*
|
|
4
|
+
* Packing a million splats is ~100 ms of main thread on a desktop (half-float
|
|
5
|
+
* conversions and an `exp` per scale axis), several times that on a phone, so
|
|
6
|
+
* the worker packs what it decodes. `packSplats` itself cannot go there - it
|
|
7
|
+
* converts through three's `DataUtils.toHalfFloat`, and the worker has no
|
|
8
|
+
* three - so this is that function again with three's conversion inlined.
|
|
9
|
+
*
|
|
10
|
+
* IT MUST STAY BIT-IDENTICAL TO `packSplats` (splat/packed-splats.ts): an
|
|
11
|
+
* `.spz` and the same scene as `.ply` have to upload the same texels. Change
|
|
12
|
+
* the two together. Like the other worker functions it reads nothing at
|
|
13
|
+
* module scope.
|
|
14
|
+
*/
|
|
15
|
+
import type { PackedSplats } from '../../splat/packed-splats';
|
|
16
|
+
import type { SplatAttributes } from '../character/types';
|
|
17
|
+
export declare function packSplatsInWorker(numSplats: number, s: SplatAttributes): PackedSplats;
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The CPU half of a SOG decode (PlayCanvas's "Spatially Ordered Gaussians":
|
|
3
|
+
* a `meta.json` and lossless WebP images, unbundled or zipped as `.sog`):
|
|
4
|
+
* image bytes to pixels to the 3DGS PLY conventions of {@link SplatAttributes}.
|
|
5
|
+
* The arithmetic is PlayCanvas's `GSplatSogData.decompress`, as the PlayCanvas
|
|
6
|
+
* build's `sog-decode.ts` reproduces it.
|
|
7
|
+
*
|
|
8
|
+
* Like `spz-decode.ts`, these functions are also the decode worker's source
|
|
9
|
+
* text (`decode-worker.ts`), so they read nothing at module scope.
|
|
10
|
+
*/
|
|
11
|
+
import type { SplatAttributes } from '../character/types';
|
|
12
|
+
/** A SOG `meta.json`: version 2 (codebooks), or the version 1 layout PlayCanvas still reads. */
|
|
13
|
+
export interface SogMeta {
|
|
14
|
+
version?: number;
|
|
15
|
+
/** Version 2. Version 1 has `means.shape[0]` instead. */
|
|
16
|
+
count?: number;
|
|
17
|
+
means: {
|
|
18
|
+
mins: number[];
|
|
19
|
+
maxs: number[];
|
|
20
|
+
files: string[];
|
|
21
|
+
shape?: number[];
|
|
22
|
+
};
|
|
23
|
+
scales: {
|
|
24
|
+
codebook?: (number | null)[];
|
|
25
|
+
mins?: number[];
|
|
26
|
+
maxs?: number[];
|
|
27
|
+
files: string[];
|
|
28
|
+
};
|
|
29
|
+
quats: {
|
|
30
|
+
files: string[];
|
|
31
|
+
};
|
|
32
|
+
sh0: {
|
|
33
|
+
codebook?: (number | null)[];
|
|
34
|
+
mins?: number[];
|
|
35
|
+
maxs?: number[];
|
|
36
|
+
files: string[];
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
/** RGBA8 pixels of the five images a DC-only decode reads, in file order (row-major from the top). */
|
|
40
|
+
export interface SogPixels {
|
|
41
|
+
means_l: Uint8Array;
|
|
42
|
+
means_u: Uint8Array;
|
|
43
|
+
quats: Uint8Array;
|
|
44
|
+
scales: Uint8Array;
|
|
45
|
+
sh0: Uint8Array;
|
|
46
|
+
}
|
|
47
|
+
/** Splat count of a SOG, from either version of its meta. */
|
|
48
|
+
export declare function sogCount(meta: SogMeta): number;
|
|
49
|
+
/**
|
|
50
|
+
* Decode images to their exact RGBA8 bytes.
|
|
51
|
+
*
|
|
52
|
+
* Not through a 2D canvas: `getImageData` hands back pixels that went through
|
|
53
|
+
* premultiplied storage, and SOG keeps data in alpha (opacity in `sh0.a`, the
|
|
54
|
+
* rotation's mode byte in `quats.a`), so every pixel with alpha below 255
|
|
55
|
+
* would come back with its colour quantised against it. An unpremultiplied
|
|
56
|
+
* `ImageBitmap` uploaded to a WebGL2 texture and read back is exact - and is
|
|
57
|
+
* what PlayCanvas itself does with these images.
|
|
58
|
+
*/
|
|
59
|
+
export declare function readImagePixels(files: Uint8Array[]): Promise<Uint8Array[]>;
|
|
60
|
+
/**
|
|
61
|
+
* SOG pixels to splat attributes, with PlayCanvas's arithmetic:
|
|
62
|
+
*
|
|
63
|
+
* - centre: 16 bits per axis over `means.mins..maxs`, stored log-encoded
|
|
64
|
+
* (`sign(t) * (exp|t| - 1)`);
|
|
65
|
+
* - rotation: three components over `±sqrt(1/2)` and a mode byte (252-255)
|
|
66
|
+
* naming which one was dropped. A mode outside that range keeps the
|
|
67
|
+
* previous splat's rotation, as PlayCanvas's iterator does;
|
|
68
|
+
* - scale and colour: a byte each per channel into a codebook (version 2) or
|
|
69
|
+
* onto `mins..maxs` (version 1), colour as the SH DC term;
|
|
70
|
+
* - opacity: `sh0.a` is the alpha (version 2) or a logit byte (version 1),
|
|
71
|
+
* returned as a logit clamped to ±40.
|
|
72
|
+
*/
|
|
73
|
+
export declare function decodeSogPixels(meta: SogMeta, px: SogPixels): SplatAttributes;
|
|
74
|
+
/** The worker's whole SOG job: the five images' bytes, in {@link SogPixels} order, to splat attributes. */
|
|
75
|
+
export declare function decodeSogTask(input: {
|
|
76
|
+
meta: SogMeta;
|
|
77
|
+
images: Uint8Array[];
|
|
78
|
+
}): Promise<{
|
|
79
|
+
numSplats: number;
|
|
80
|
+
splats: SplatAttributes;
|
|
81
|
+
}>;
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* SOG scenes: a `meta.json` beside its WebP images (what a streaming LOD
|
|
3
|
+
* bundle is made of, one per chunk), or the same files zipped into one `.sog`.
|
|
4
|
+
* Fetching and unzipping happen here; decoding the images and the splats is
|
|
5
|
+
* the decode worker's (`sog-decode.ts`).
|
|
6
|
+
*/
|
|
7
|
+
import type { PackedSplats } from '../../splat/packed-splats';
|
|
8
|
+
/** `url` resolved against `base`, itself resolved against the page. */
|
|
9
|
+
export declare function resolveUrl(url: string, base: string): string;
|
|
10
|
+
/**
|
|
11
|
+
* Fetch and decode an unbundled SOG from its `meta.json`; the images are
|
|
12
|
+
* fetched from beside it. Higher SH bands (`shN`) are not fetched: splats here
|
|
13
|
+
* are lit by their DC colour.
|
|
14
|
+
*/
|
|
15
|
+
export declare function loadSogMeta(url: string): Promise<PackedSplats>;
|
|
16
|
+
/** Decode a bundled `.sog` (a zip of `meta.json` and its images) held in memory. */
|
|
17
|
+
export declare function decodeSogBundle(file: Uint8Array): Promise<PackedSplats>;
|
package/dist/types/math.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* The math kernel of the skeletal core: PlayCanvas's `Vec3` / `Quat` / `Mat4`.
|
|
3
3
|
*
|
|
4
4
|
* The rig, animation and skinning code is shared with the PlayCanvas build of
|
|
5
5
|
* this engine and was written against that engine's `Vec3` / `Quat` / `Mat4`.
|
|
@@ -9,17 +9,31 @@
|
|
|
9
9
|
*
|
|
10
10
|
* Deliberately NOT `THREE.Vector3` and friends: the conventions differ in ways
|
|
11
11
|
* that silently change results (`lerp(a, b, t)` vs `lerp(v, t)`, a two-argument
|
|
12
|
-
* `cross`, a `Float32Array`-backed matrix), and a port that
|
|
13
|
-
* hand would be a port nobody could diff against the original.
|
|
12
|
+
* `cross`, a `Float32Array`-backed matrix, angles in degrees), and a port that
|
|
13
|
+
* swapped them by hand would be a port nobody could diff against the original.
|
|
14
14
|
*
|
|
15
|
-
*
|
|
16
|
-
* the
|
|
15
|
+
* Exported because `Pose`, `Armature.getBoneWorldMatrix` and the rest of the
|
|
16
|
+
* rig hand these out, and game code ported from the PlayCanvas build calls
|
|
17
|
+
* PlayCanvas methods on them. Each class carries the whole of PlayCanvas
|
|
18
|
+
* 2.23's API for that class (`Vec4` arguments take any `{x, y, z, w}`), with
|
|
19
|
+
* its formulas, so such code can import them in place of `pc.Vec3` and
|
|
20
|
+
* friends. `Mat4.data` has the layout of `THREE.Matrix4.elements`:
|
|
21
|
+
* `new Matrix4().fromArray(m.data)` crosses over.
|
|
22
|
+
*
|
|
23
|
+
* @module
|
|
24
|
+
* @group Math
|
|
25
|
+
*/
|
|
26
|
+
/**
|
|
27
|
+
* PlayCanvas's `Vec3`.
|
|
28
|
+
*
|
|
29
|
+
* @group Math
|
|
17
30
|
*/
|
|
18
31
|
export declare class Vec3 {
|
|
19
32
|
x: number;
|
|
20
33
|
y: number;
|
|
21
34
|
z: number;
|
|
22
|
-
|
|
35
|
+
/** Three numbers, or one array-like of three. */
|
|
36
|
+
constructor(x?: number | ArrayLike<number>, y?: number, z?: number);
|
|
23
37
|
set(x: number, y: number, z: number): this;
|
|
24
38
|
copy(rhs: {
|
|
25
39
|
x: number;
|
|
@@ -29,20 +43,72 @@ export declare class Vec3 {
|
|
|
29
43
|
clone(): Vec3;
|
|
30
44
|
add(rhs: Vec3): this;
|
|
31
45
|
add2(lhs: Vec3, rhs: Vec3): this;
|
|
46
|
+
sub(rhs: Vec3): this;
|
|
32
47
|
sub2(lhs: Vec3, rhs: Vec3): this;
|
|
33
48
|
mulScalar(scalar: number): this;
|
|
34
49
|
dot(rhs: Vec3): number;
|
|
35
50
|
cross(lhs: Vec3, rhs: Vec3): this;
|
|
36
51
|
length(): number;
|
|
37
|
-
|
|
52
|
+
/** Normalize `src` (default: this) into this. A zero vector is left as it was. */
|
|
53
|
+
normalize(src?: Vec3): this;
|
|
38
54
|
lerp(lhs: Vec3, rhs: Vec3, alpha: number): this;
|
|
55
|
+
addScalar(scalar: number): this;
|
|
56
|
+
/** `this += rhs * scalar`. */
|
|
57
|
+
addScaled(rhs: Vec3, scalar: number): this;
|
|
58
|
+
subScalar(scalar: number): this;
|
|
59
|
+
/** Component-wise. */
|
|
60
|
+
mul(rhs: Vec3): this;
|
|
61
|
+
/** Component-wise. */
|
|
62
|
+
mul2(lhs: Vec3, rhs: Vec3): this;
|
|
63
|
+
/** {@link mulScalar}. */
|
|
64
|
+
scale(scalar: number): this;
|
|
65
|
+
/** Component-wise. */
|
|
66
|
+
div(rhs: Vec3): this;
|
|
67
|
+
/** Component-wise. */
|
|
68
|
+
div2(lhs: Vec3, rhs: Vec3): this;
|
|
69
|
+
divScalar(scalar: number): this;
|
|
70
|
+
distance(rhs: Vec3): number;
|
|
71
|
+
distanceSq(rhs: Vec3): number;
|
|
72
|
+
lengthSq(): number;
|
|
73
|
+
equals(rhs: Vec3): boolean;
|
|
74
|
+
equalsApprox(rhs: Vec3, epsilon?: number): boolean;
|
|
75
|
+
floor(src?: Vec3): this;
|
|
76
|
+
ceil(src?: Vec3): this;
|
|
77
|
+
round(src?: Vec3): this;
|
|
78
|
+
/** Component-wise minimum with `rhs`. */
|
|
79
|
+
min(rhs: Vec3): this;
|
|
80
|
+
/** Component-wise maximum with `rhs`. */
|
|
81
|
+
max(rhs: Vec3): this;
|
|
82
|
+
/** Project this onto `rhs`. */
|
|
83
|
+
project(rhs: Vec3): this;
|
|
84
|
+
/** Read three numbers from `arr` at `offset`; missing ones keep their value. */
|
|
85
|
+
fromArray(arr: ArrayLike<number>, offset?: number): this;
|
|
86
|
+
toArray<T extends {
|
|
87
|
+
[i: number]: number;
|
|
88
|
+
} = number[]>(arr?: T, offset?: number): T;
|
|
89
|
+
toString(): string;
|
|
90
|
+
static readonly ZERO: Readonly<Vec3>;
|
|
91
|
+
static readonly HALF: Readonly<Vec3>;
|
|
92
|
+
static readonly ONE: Readonly<Vec3>;
|
|
93
|
+
static readonly UP: Readonly<Vec3>;
|
|
94
|
+
static readonly DOWN: Readonly<Vec3>;
|
|
95
|
+
static readonly RIGHT: Readonly<Vec3>;
|
|
96
|
+
static readonly LEFT: Readonly<Vec3>;
|
|
97
|
+
static readonly FORWARD: Readonly<Vec3>;
|
|
98
|
+
static readonly BACK: Readonly<Vec3>;
|
|
39
99
|
}
|
|
100
|
+
/**
|
|
101
|
+
* PlayCanvas's `Quat`. Angles in and out are in degrees.
|
|
102
|
+
*
|
|
103
|
+
* @group Math
|
|
104
|
+
*/
|
|
40
105
|
export declare class Quat {
|
|
41
106
|
x: number;
|
|
42
107
|
y: number;
|
|
43
108
|
z: number;
|
|
44
109
|
w: number;
|
|
45
|
-
|
|
110
|
+
/** Four numbers, or one array-like of four. */
|
|
111
|
+
constructor(x?: number | ArrayLike<number>, y?: number, z?: number, w?: number);
|
|
46
112
|
set(x: number, y: number, z: number, w: number): this;
|
|
47
113
|
copy(rhs: {
|
|
48
114
|
x: number;
|
|
@@ -51,19 +117,77 @@ export declare class Quat {
|
|
|
51
117
|
w: number;
|
|
52
118
|
}): this;
|
|
53
119
|
clone(): Quat;
|
|
54
|
-
|
|
120
|
+
/** Conjugate `src` (default: this) into this. */
|
|
121
|
+
conjugate(src?: Quat): this;
|
|
55
122
|
dot(other: Quat): number;
|
|
56
123
|
length(): number;
|
|
57
|
-
|
|
58
|
-
|
|
124
|
+
/** `this = src * scalar`, `src` defaulting to this. */
|
|
125
|
+
mulScalar(scalar: number, src?: Quat): this;
|
|
126
|
+
/** Normalize `src` (default: this) into this; a zero quaternion becomes the identity. */
|
|
127
|
+
normalize(src?: Quat): this;
|
|
59
128
|
/** `this = lhs * rhs`. Safe when `this` aliases either operand. */
|
|
60
129
|
mul2(lhs: Quat, rhs: Quat): this;
|
|
61
130
|
mul(rhs: Quat): this;
|
|
62
131
|
slerp(lhs: Quat, rhs: Quat, alpha: number): this;
|
|
132
|
+
/** Rotate `vec` by this quaternion. */
|
|
133
|
+
transformVector(vec: {
|
|
134
|
+
x: number;
|
|
135
|
+
y: number;
|
|
136
|
+
z: number;
|
|
137
|
+
}, res?: Vec3): Vec3;
|
|
63
138
|
/** Rotation of the upper 3x3 of `m`, with any scale (and a mirror) divided out. */
|
|
64
139
|
setFromMat4(m: Mat4): this;
|
|
140
|
+
lengthSq(): number;
|
|
141
|
+
/** The inverse of `src` (default: this), into this. */
|
|
142
|
+
invert(src?: Quat): this;
|
|
143
|
+
/** Normalized linear blend from `lhs` to `rhs`, taking the short way round. */
|
|
144
|
+
lerp(lhs: Quat, rhs: Quat, alpha: number): this;
|
|
145
|
+
equals(rhs: Quat): boolean;
|
|
146
|
+
equalsApprox(rhs: Quat, epsilon?: number): boolean;
|
|
147
|
+
/** A rotation of `angle` degrees about the unit vector `axis`. */
|
|
148
|
+
setFromAxisAngle(axis: {
|
|
149
|
+
x: number;
|
|
150
|
+
y: number;
|
|
151
|
+
z: number;
|
|
152
|
+
}, angle: number): this;
|
|
153
|
+
/**
|
|
154
|
+
* Write this rotation's axis into `axis` and return its angle in degrees.
|
|
155
|
+
* The axis is flipped to have no negative component where it can be, the
|
|
156
|
+
* angle with it.
|
|
157
|
+
*/
|
|
158
|
+
getAxisAngle(axis: {
|
|
159
|
+
x: number;
|
|
160
|
+
y: number;
|
|
161
|
+
z: number;
|
|
162
|
+
}): number;
|
|
163
|
+
/** From Euler angles in degrees, applied X, then Y, then Z (as PlayCanvas). */
|
|
164
|
+
setFromEulerAngles(ex: number | Vec3, ey?: number, ez?: number): this;
|
|
165
|
+
/** This rotation as Euler angles in degrees (see {@link setFromEulerAngles}). */
|
|
166
|
+
getEulerAngles(eulers?: Vec3): Vec3;
|
|
167
|
+
/** The shortest rotation taking unit vector `from` to unit vector `to`. */
|
|
168
|
+
setFromDirections(from: Vec3, to: Vec3): this;
|
|
169
|
+
/** Read four numbers from `arr` at `offset`; missing ones keep their value. */
|
|
170
|
+
fromArray(arr: ArrayLike<number>, offset?: number): this;
|
|
171
|
+
toArray<T extends {
|
|
172
|
+
[i: number]: number;
|
|
173
|
+
} = number[]>(arr?: T, offset?: number): T;
|
|
174
|
+
toString(): string;
|
|
175
|
+
static readonly IDENTITY: Readonly<Quat>;
|
|
176
|
+
static readonly ZERO: Readonly<Quat>;
|
|
65
177
|
}
|
|
66
|
-
|
|
178
|
+
type XYZW = {
|
|
179
|
+
x: number;
|
|
180
|
+
y: number;
|
|
181
|
+
z: number;
|
|
182
|
+
w: number;
|
|
183
|
+
};
|
|
184
|
+
/**
|
|
185
|
+
* PlayCanvas's `Mat4`: column-major 4x4, `Float32Array`-backed, the same
|
|
186
|
+
* element layout as `THREE.Matrix4.elements`. Angles in and out are in
|
|
187
|
+
* degrees.
|
|
188
|
+
*
|
|
189
|
+
* @group Math
|
|
190
|
+
*/
|
|
67
191
|
export declare class Mat4 {
|
|
68
192
|
data: Float32Array;
|
|
69
193
|
constructor();
|
|
@@ -76,7 +200,68 @@ export declare class Mat4 {
|
|
|
76
200
|
/** `this = lhs * rhs`. Safe when `this` aliases either operand. */
|
|
77
201
|
mul2(lhs: Mat4, rhs: Mat4): this;
|
|
78
202
|
mul(rhs: Mat4): this;
|
|
79
|
-
|
|
203
|
+
/** The inverse of `src` (default: this), into this. A singular matrix gives the identity. */
|
|
204
|
+
invert(src?: Mat4): this;
|
|
80
205
|
getTranslation(t?: Vec3): Vec3;
|
|
81
206
|
getScale(scale?: Vec3): Vec3;
|
|
207
|
+
/** Copy 16 column-major numbers in; {@link setFromArray} under PlayCanvas's name. */
|
|
208
|
+
set(src: ArrayLike<number>): this;
|
|
209
|
+
add2(lhs: Mat4, rhs: Mat4): this;
|
|
210
|
+
add(rhs: Mat4): this;
|
|
211
|
+
equals(rhs: Mat4): boolean;
|
|
212
|
+
isIdentity(): boolean;
|
|
213
|
+
/** `this = lhs * rhs` for affine matrices (the bottom rows taken as 0 0 0 1). */
|
|
214
|
+
mulAffine2(lhs: Mat4, rhs: Mat4): this;
|
|
215
|
+
/** `vec` as a point (w = 1) through this matrix. */
|
|
216
|
+
transformPoint(vec: {
|
|
217
|
+
x: number;
|
|
218
|
+
y: number;
|
|
219
|
+
z: number;
|
|
220
|
+
}, res?: Vec3): Vec3;
|
|
221
|
+
/** `vec` as a direction (w = 0) through this matrix. */
|
|
222
|
+
transformVector(vec: {
|
|
223
|
+
x: number;
|
|
224
|
+
y: number;
|
|
225
|
+
z: number;
|
|
226
|
+
}, res?: Vec3): Vec3;
|
|
227
|
+
transformVec4<T extends XYZW = XYZW>(vec: XYZW, res?: T): T;
|
|
228
|
+
/** A transform at `position` whose -Z looks at `target`, with `up` as near up as it can be. */
|
|
229
|
+
setLookAt(position: Vec3, target: Vec3, up: Vec3): this;
|
|
230
|
+
setFrustum(left: number, right: number, bottom: number, top: number, znear: number, zfar: number): this;
|
|
231
|
+
/** `fov` in degrees: vertical, or horizontal when `fovIsHorizontal`. */
|
|
232
|
+
setPerspective(fov: number, aspect: number, znear: number, zfar: number, fovIsHorizontal?: boolean): this;
|
|
233
|
+
setOrtho(left: number, right: number, bottom: number, top: number, near: number, far: number): this;
|
|
234
|
+
/** A rotation of `angle` degrees about the unit vector `axis`. */
|
|
235
|
+
setFromAxisAngle(axis: {
|
|
236
|
+
x: number;
|
|
237
|
+
y: number;
|
|
238
|
+
z: number;
|
|
239
|
+
}, angle: number): this;
|
|
240
|
+
setTranslate(x: number, y: number, z: number): this;
|
|
241
|
+
setScale(x: number, y: number, z: number): this;
|
|
242
|
+
setViewport(x: number, y: number, width: number, height: number): this;
|
|
243
|
+
/** Reflection about the plane `normal · p = distance`. */
|
|
244
|
+
setReflection(normal: {
|
|
245
|
+
x: number;
|
|
246
|
+
y: number;
|
|
247
|
+
z: number;
|
|
248
|
+
}, distance: number): this;
|
|
249
|
+
/** The transpose of `src` (default: this), into this. */
|
|
250
|
+
transpose(src?: Mat4): this;
|
|
251
|
+
/** The X axis (first column). */
|
|
252
|
+
getX(x?: Vec3): Vec3;
|
|
253
|
+
/** The Y axis (second column). */
|
|
254
|
+
getY(y?: Vec3): Vec3;
|
|
255
|
+
/** The Z axis (third column). */
|
|
256
|
+
getZ(z?: Vec3): Vec3;
|
|
257
|
+
/** `-1` when the axes are mirrored, else `1`. */
|
|
258
|
+
get scaleSign(): number;
|
|
259
|
+
/** A rotation from Euler angles in degrees (see {@link Quat.setFromEulerAngles}). */
|
|
260
|
+
setFromEulerAngles(ex: number, ey: number, ez: number): this;
|
|
261
|
+
/** The rotation as Euler angles in degrees, with any scale divided out. */
|
|
262
|
+
getEulerAngles(eulers?: Vec3): Vec3;
|
|
263
|
+
toString(): string;
|
|
264
|
+
static readonly IDENTITY: Readonly<Mat4>;
|
|
265
|
+
static readonly ZERO: Readonly<Mat4>;
|
|
82
266
|
}
|
|
267
|
+
export {};
|