Core: Introduce Coordinate System (#490)

* Core: Introduce Coordinate System

* CubeCamera

Author: Methuselah96

types/three/src/cameras/Camera.d.ts

@@ -1,7 +1,8 @@
-import { Matrix4 } from './../math/Matrix4';
-import { Vector3 } from './../math/Vector3';
-import { Object3D } from './../core/Object3D';
-import { Layers } from '../Three';
+import { Matrix4 } from '../math/Matrix4';
+import { Vector3 } from '../math/Vector3';
+import { Object3D } from '../core/Object3D';
+import { Layers } from '../core/Layers';
+import { CoordinateSystem } from '../constants';
 
 /**
  * Abstract base class for cameras
@@ -59,6 +60,8 @@ export abstract class Camera extends Object3D {
      */
     projectionMatrixInverse: Matrix4;
 
+    coordinateSystem: CoordinateSystem;
+
     /**
      * Returns a {@link THREE.Vector3 | Vector3} representing the world space direction in which the {@link Camera} is looking.
      * @remarks Note: A {@link Camera} looks down its local, negative z-axis.

types/three/src/cameras/CubeCamera.d.ts

@@ -2,6 +2,7 @@ import { WebGLCubeRenderTarget } from './../renderers/WebGLCubeRenderTarget';
 import { Scene } from './../scenes/Scene';
 import { WebGLRenderer } from './../renderers/WebGLRenderer';
 import { Object3D } from './../core/Object3D';
+import { CoordinateSystem } from '../constants';
 
 /**
  * Creates **6** {@link THREE.PerspectiveCamera | cameras} that render to a {@link THREE.WebGLCubeRenderTarget | WebGLCubeRenderTarget}.
@@ -53,6 +54,10 @@ export class CubeCamera extends Object3D {
      */
     renderTarget: WebGLCubeRenderTarget;
 
+    coordinateSystem: CoordinateSystem;
+
+    updateCoordinateSystem(): void;
+
     /**
      * Call this to update the {@link CubeCamera.renderTarget | renderTarget}.
      * @param renderer The current WebGL renderer

types/three/src/constants.d.ts

@@ -799,6 +799,10 @@ export const GLSL1: '100';
 export const GLSL3: '300 es';
 export type GLSLVersion = typeof GLSL1 | typeof GLSL3;
 
+export const WebGLCoordinateSystem: 2000;
+export const WebGPUCoordinateSystem: 2001;
+export type CoordinateSystem = typeof WebGLCoordinateSystem | typeof WebGPUCoordinateSystem;
+
 ///////////////////////////////////////////////////////////////////////////////
 // Texture - Internal Pixel Formats
 

types/three/src/math/Frustum.d.ts

@@ -5,6 +5,7 @@ import { Sprite } from './../objects/Sprite';
 import { Sphere } from './Sphere';
 import { Box3 } from './Box3';
 import { Vector3 } from './Vector3';
+import { CoordinateSystem } from '../constants';
 
 /**
  * Frustums are used to determine what is inside the camera's field of view. They help speed up the rendering process.
@@ -20,7 +21,7 @@ export class Frustum {
     set(p0: Plane, p1: Plane, p2: Plane, p3: Plane, p4: Plane, p5: Plane): Frustum;
     clone(): this;
     copy(frustum: Frustum): this;
-    setFromProjectionMatrix(m: Matrix4): this;
+    setFromProjectionMatrix(m: Matrix4, coordinateSystem?: CoordinateSystem): this;
     intersectsObject(object: Object3D): boolean;
     intersectsSprite(sprite: Sprite): boolean;
     intersectsSphere(sphere: Sphere): boolean;

types/three/src/math/Matrix4.d.ts

@@ -2,6 +2,7 @@ import { Vector3 } from './Vector3';
 import { Euler } from './Euler';
 import { Quaternion } from './Quaternion';
 import { Matrix, Matrix3 } from './Matrix3';
+import { CoordinateSystem } from '../constants';
 
 export type Matrix4Tuple = [
     number,
@@ -227,12 +228,28 @@ export class Matrix4 implements Matrix {
     /**
      * Creates a perspective projection matrix.
      */
-    makePerspective(left: number, right: number, top: number, bottom: number, near: number, far: number): Matrix4;
+    makePerspective(
+        left: number,
+        right: number,
+        top: number,
+        bottom: number,
+        near: number,
+        far: number,
+        coordinateSystem?: CoordinateSystem,
+    ): Matrix4;
 
     /**
      * Creates an orthographic projection matrix.
      */
-    makeOrthographic(left: number, right: number, top: number, bottom: number, near: number, far: number): Matrix4;
+    makeOrthographic(
+        left: number,
+        right: number,
+        top: number,
+        bottom: number,
+        near: number,
+        far: number,
+        coordinateSystem?: CoordinateSystem,
+    ): Matrix4;
     equals(matrix: Matrix4): boolean;
 
     /**

types/three/src/renderers/WebGLRenderer.d.ts

@@ -14,7 +14,7 @@ import { WebGLRenderTarget } from './WebGLRenderTarget';
 import { WebGLMultipleRenderTargets } from './WebGLMultipleRenderTargets';
 import { Object3D } from './../core/Object3D';
 import { Material } from './../materials/Material';
-import { ToneMapping, ShadowMapType, CullFace, TextureEncoding, ColorSpace } from '../constants';
+import { ToneMapping, ShadowMapType, CullFace, TextureEncoding, ColorSpace, WebGLCoordinateSystem } from '../constants';
 import { WebXRManager } from '../renderers/webxr/WebXRManager';
 import { BufferGeometry } from './../core/BufferGeometry';
 import { OffscreenCanvas, Texture } from '../textures/Texture';
@@ -200,6 +200,8 @@ export class WebGLRenderer implements Renderer {
      */
     outputColorSpace: ColorSpace;
 
+    get coordinateSystem(): typeof WebGLCoordinateSystem;
+
     /**
      * @default true
      */