TypeScript support (#188)

* feat: .d.ts type annotations * Attribute expects buffersource * Narrow AttributeData, mend array methods * chore: lowercase path directory * chore: import house cleaning * chore: format with prettier config * chore: remove unnecessary declare * feat: add tuple type to set method * feat: core/math updates * feat: extras * feat: update package.json to include src files * chore: import order adjustment * chore: Transform.setParent() description adjustment * feat: add KTXTexture declaration * fix: Orbit constructor object is a Camera * fix: update package.json exports for types and default * fix: remove unnecessary fov intersection * chore: remove unnecessary intersection for CompressedImage --------- Co-authored-by: Cody Bennett <[email protected]>
oframe · Oct 6, 2023 · 65980cf · 65980cf
1 parent 247aa67
commit 65980cf
Show file tree

Hide file tree

Showing 62 changed files with 2,498 additions and 3 deletions.
diff --git a/package.json b/package.json
@@ -2,10 +2,17 @@
     "name": "ogl",
     "version": "1.0.0",
     "description": "WebGL Library",
-    "main": "./src/index.js",
-    "exports": "./src/index.js",
     "type": "module",
+    "main": "./src/index.js",
+    "exports": {
+        ".": {
+            "types": "./types/index.d.ts",
+            "default": "./src/index.js"
+        },
+        "./src/*": "./src/*"
+    },
     "sideEffects": false,
+    "types": "./types/index.d.ts",
     "directories": {
         "example": "examples"
     },

diff --git a/src/core/Transform.js b/src/core/Transform.js
@@ -12,6 +12,7 @@ export class Transform {
         this.matrix = new Mat4();
         this.worldMatrix = new Mat4();
         this.matrixAutoUpdate = true;
+        this.worldMatrixNeedsUpdate = false;
 
         this.position = new Vec3();
         this.quaternion = new Quat();

diff --git a/src/extras/Path/BaseSegment.js → src/extras/path/BaseSegment.js b/src/extras/Path/BaseSegment.js → src/extras/path/BaseSegment.js
diff --git a/src/extras/Path/CubicBezierSegment.js → src/extras/path/CubicBezierSegment.js b/src/extras/Path/CubicBezierSegment.js → src/extras/path/CubicBezierSegment.js
diff --git a/src/extras/Path/LineSegment.js → src/extras/path/LineSegment.js b/src/extras/Path/LineSegment.js → src/extras/path/LineSegment.js
diff --git a/src/extras/Path/Path.js → src/extras/path/Path.js b/src/extras/Path/Path.js → src/extras/path/Path.js
diff --git a/src/extras/Path/QuadraticBezierSegment.js → src/extras/path/QuadraticBezierSegment.js b/src/extras/Path/QuadraticBezierSegment.js → src/extras/path/QuadraticBezierSegment.js
diff --git a/src/extras/Path/utils.js → src/extras/path/utils.js b/src/extras/Path/utils.js → src/extras/path/utils.js
diff --git a/src/index.js b/src/index.js
@@ -28,7 +28,7 @@ export { Torus } from './extras/Torus.js';
 export { Orbit } from './extras/Orbit.js';
 export { Raycast } from './extras/Raycast.js';
 export { Curve } from './extras/Curve.js';
-export { Path } from './extras/Path/Path.js';
+export { Path } from './extras/path/Path.js';
 export { Tube } from './extras/Tube.js';
 export { Post } from './extras/Post.js';
 export { Skin } from './extras/Skin.js';

diff --git a/types/core/Camera.d.ts b/types/core/Camera.d.ts
@@ -0,0 +1,72 @@
+import { Transform } from './Transform.js';
+import { Mat4 } from '../math/Mat4.js';
+import { Vec3 } from '../math/Vec3.js';
+
+import type { OGLRenderingContext } from './Renderer.js';
+import type { Vec3Tuple } from '../math/Vec3.js';
+import type { Mesh } from './Mesh.js';
+
+export interface CameraOptions {
+    near: number;
+    far: number;
+    fov: number;
+    aspect: number;
+    left: number;
+    right: number;
+    bottom: number;
+    top: number;
+    zoom: number;
+}
+
+export interface PerspectiveOptions extends Pick<CameraOptions, 'near' | 'far' | 'fov' | 'aspect'> {}
+
+export interface OrthographicOptions extends Pick<CameraOptions, 'near' | 'far' | 'left' | 'right' | 'bottom' | 'top' | 'zoom'> {}
+
+export type CameraType = 'perspective' | 'orthographic';
+
+/**
+ * A perspective or orthographic camera.
+ * @see {@link https://github.com/oframe/ogl/blob/master/src/core/Camera.js | Source}
+ */
+export class Camera extends Transform {
+    projectionMatrix: Mat4;
+    viewMatrix: Mat4;
+    projectionViewMatrix: Mat4;
+    worldPosition: Vec3;
+
+    type: CameraType;
+
+    near: number;
+    far: number;
+    fov: number;
+    aspect: number;
+    left: number;
+    right: number;
+    bottom: number;
+    top: number;
+    zoom: number;
+
+    frustum: (Vec3 & {
+        constant: number;
+    })[];
+
+    constructor(gl: OGLRenderingContext, options?: Partial<CameraOptions>);
+
+    perspective(options?: Partial<PerspectiveOptions>): this;
+
+    orthographic(options?: Partial<OrthographicOptions>): this;
+
+    updateMatrixWorld(): this;
+
+    lookAt(target: Vec3 | Vec3Tuple): this;
+
+    project(v: Vec3): this;
+
+    unproject(v: Vec3): this;
+
+    updateFrustum(): void;
+
+    frustumIntersectsMesh(node: Mesh, worldMatrix?: Mat4): boolean;
+
+    frustumIntersectsSphere(center: Vec3, radius: number): boolean;
+}
diff --git a/types/core/Geometry.d.ts b/types/core/Geometry.d.ts
@@ -0,0 +1,89 @@
+import { Vec3 } from '../math/Vec3.js';
+
+import type { OGLRenderingContext, RenderState } from './Renderer.js';
+import type { Program } from './Program.js';
+
+export type AttributeMap = Record<string, Partial<Attribute>>;
+
+export type AttributeData = Float32Array | Uint32Array | Uint16Array;
+
+export interface Attribute {
+    data: AttributeData;
+    size: number;
+    instanced: null | number | boolean;
+    type: GLenum;
+    normalized: boolean;
+
+    buffer: WebGLBuffer;
+    stride: number;
+    offset: number;
+    count: number;
+    target: number;
+    id: number;
+    divisor: number;
+    needsUpdate: boolean;
+    usage: number;
+}
+
+export interface Bounds {
+    min: Vec3;
+    max: Vec3;
+    center: Vec3;
+    scale: Vec3;
+    radius: number;
+}
+
+export type GeometryRaycast = 'sphere' | 'box';
+
+/**
+ * A mesh, line, or point geometry.
+ * @see {@link https://github.com/oframe/ogl/blob/master/src/core/Geometry.js | Source}
+ */
+export class Geometry {
+    gl: OGLRenderingContext;
+    attributes: AttributeMap;
+    id: number;
+
+    VAOs: {
+        [programKey: string]: WebGLVertexArrayObject;
+    };
+
+    drawRange: {
+        start: number;
+        count: number;
+    };
+    instancedCount: number;
+
+    glState: RenderState;
+
+    isInstanced: boolean;
+    bounds: Bounds;
+
+    raycast?: GeometryRaycast; // User defined
+
+    constructor(gl: OGLRenderingContext, attributes?: AttributeMap);
+
+    addAttribute(key: string, attr: Partial<Attribute>): number | undefined;
+
+    updateAttribute(attr: Partial<Attribute>): void;
+
+    setIndex(value: Attribute): void;
+
+    setDrawRange(start: number, count: number): void;
+
+    setInstancedCount(value: number): void;
+
+    createVAO(program: Program): void;
+
+    bindAttributes(program: Program): void;
+
+    draw(options: { program: Program; mode?: number }): void;
+
+    getPosition(): Partial<Attribute>;
+
+    computeBoundingBox(attr: Partial<Attribute>): void;
+
+    computeBoundingSphere(attr?: Partial<Attribute>): void;
+
+    remove(): void;
+}
diff --git a/types/core/Mesh.d.ts b/types/core/Mesh.d.ts
@@ -0,0 +1,67 @@
+import { Transform } from './Transform.js';
+import { Mat3 } from '../math/Mat3.js';
+import { Mat4 } from '../math/Mat4.js';
+
+import type { OGLRenderingContext } from './Renderer.js';
+import type { Vec2 } from '../math/Vec2.js';
+import type { Vec3 } from '../math/Vec3.js';
+import type { Geometry } from './Geometry.js';
+import type { Program } from './Program.js';
+import type { Camera } from './Camera.js';
+
+export interface MeshOptions<
+    TGeometry extends Geometry = Geometry,
+    TProgram extends Program = Program,
+> {
+    geometry: TGeometry;
+    program: TProgram;
+    mode: GLenum;
+    frustumCulled: boolean;
+    renderOrder: number;
+}
+
+export type MeshRenderCallback = (renderInfo: { mesh: Mesh; camera?: Camera }) => any;
+
+export interface RaycastHit {
+    localPoint: Vec3;
+    distance: number;
+    point: Vec3;
+    faceNormal: Vec3;
+    localFaceNormal: Vec3;
+    uv: Vec2;
+    localNormal: Vec3;
+    normal: Vec3;
+}
+
+/**
+ * Represents a {@link https://en.wikipedia.org/wiki/Polygon_mesh | polygon mesh}.
+ * @see {@link https://github.com/oframe/ogl/blob/master/src/core/Mesh.js | Source}
+ */
+export class Mesh<
+    TGeometry extends Geometry = Geometry,
+    TProgram extends Program = Program,
+> extends Transform {
+    gl: OGLRenderingContext;
+    id: number;
+    geometry: TGeometry;
+    program: TProgram;
+    mode: GLenum;
+
+    frustumCulled: boolean;
+
+    renderOrder: number;
+    modelViewMatrix: Mat4;
+    normalMatrix: Mat3;
+    beforeRenderCallbacks: MeshRenderCallback[];
+    afterRenderCallbacks: MeshRenderCallback[];
+
+    hit?: Partial<RaycastHit>; // Set from raycaster
+
+    constructor(gl: OGLRenderingContext, options?: Partial<MeshOptions>);
+
+    onBeforeRender(f: MeshRenderCallback): this;
+
+    onAfterRender(f: MeshRenderCallback): this;
+
+    draw(options?: { camera?: Camera }): void;
+}
diff --git a/types/core/Program.d.ts b/types/core/Program.d.ts
@@ -0,0 +1,58 @@
+import type { OGLRenderingContext, BlendFunc, BlendEquation } from './Renderer';
+
+export interface ProgramOptions {
+    vertex: string;
+    fragment: string;
+    uniforms: Record<string, any>;
+    transparent: boolean;
+    cullFace: GLenum | false | null;
+    frontFace: GLenum;
+    depthTest: boolean;
+    depthWrite: boolean;
+    depthFunc: GLenum;
+}
+
+export interface UniformInfo extends WebGLActiveInfo {
+    uniformName: string;
+    nameComponents: string[];
+    isStruct: boolean;
+    isStructArray: boolean;
+    structIndex: number;
+    structProperty: string;
+}
+
+/**
+ * A WebGL program.
+ * @see {@link https://github.com/oframe/ogl/blob/master/src/core/Program.js | Source}
+ */
+export class Program {
+    gl: OGLRenderingContext;
+    uniforms: Record<string, any>;
+    id: number;
+
+    transparent: boolean;
+    cullFace: GLenum | false | null;
+    frontFace: GLenum;
+    depthTest: boolean;
+    depthWrite: boolean;
+    depthFunc: GLenum;
+    blendFunc: BlendFunc;
+    blendEquation: BlendEquation;
+
+    program: WebGLProgram;
+    uniformLocations: Map<UniformInfo, WebGLUniformLocation>;
+    attributeLocations: Map<WebGLActiveInfo, GLint>;
+    attributeOrder: string;
+
+    constructor(gl: OGLRenderingContext, options?: Partial<ProgramOptions>);
+
+    setBlendFunc(src: GLenum, dst: GLenum, srcAlpha?: GLenum, dstAlpha?: GLenum): void;
+
+    setBlendEquation(modeRGB: GLenum, modeAlpha: GLenum): void;
+
+    applyState(): void;
+
+    use(options?: { flipFaces?: boolean }): void;
+
+    remove(): void;
+}
diff --git a/types/core/RenderTarget.d.ts b/types/core/RenderTarget.d.ts
@@ -0,0 +1,46 @@
+import { Texture } from './Texture.js';
+
+import type { OGLRenderingContext } from './Renderer.js';
+
+export interface RenderTargetOptions {
+    width: number;
+    height: number;
+    target: GLenum;
+    color: number;
+    depth: boolean;
+    stencil: boolean;
+    depthTexture: boolean;
+    wrapS: GLenum;
+    wrapT: GLenum;
+    minFilter: GLenum;
+    magFilter: GLenum;
+    type: GLenum;
+    format: GLenum;
+    internalFormat: GLenum;
+    unpackAlignment: number;
+    premultiplyAlpha: boolean;
+}
+
+/**
+ * A render target.
+ * @see {@link https://github.com/oframe/ogl/blob/master/src/core/RenderTarget.js | Source}
+ */
+export class RenderTarget {
+    gl: OGLRenderingContext;
+    width: number;
+    height: number;
+    depth: boolean;
+    buffer: WebGLFramebuffer;
+    target: number;
+
+    textures: Texture[];
+    texture: Texture;
+    depthTexture: Texture;
+    depthBuffer: WebGLRenderbuffer;
+    stencilBuffer: WebGLRenderbuffer;
+    depthStencilBuffer: WebGLRenderbuffer;
+
+    constructor(gl: OGLRenderingContext, options?: Partial<RenderTargetOptions>);
+
+    setSize(width: number, height: number): void;
+}