gl-matrix-extension v0.1.0

glMatrix Extension

A set of utilities for interactive web content creation, following gl-matrix idioms, The feature set includes 2D rects, sphere utils, 3D volumes utils, and some math functions. In addition we packed a id generation module and a polyfill for performance.now() and requestionAnimationFrame()

Contribution

Here is some suggestions for contributions

1. Help with the documentation / docs generation.
2. Suggest or setup testing.
3. Discuss future development of the library.

Developer guide & Naming convention

1. Extending built-ins: we create a new namespace with Ext as suffix, like for vec2 it will be vec2Ext;
2. New data structures: we will use the same convention as gl-matrix, lowercase the name, if it can have dimension size we append it as suffix, (examples: rect, aabb2, aabb3, orect, oaabb3, sphere, circle, octree);
3. Intersections: in some situations the user might just need to know if two things intersect, in that case she should use the intersect${Thing} functions, and when they are ready to get more details she should call intersection${Thing}, the getIntersection${Thing} should not do any checking, it is assumed that the user already did the intersection test, and if the intersection fails, the result is undefined (I mean an undefined result not literal undefined). We might consider a tryGetIntersection${Thing}(out, ...): boolean)

Features / Roadmap

• Misc
  • cuid a lazy loaded cuid module.
  • now a lazy loaded performance.now() polyfill.
  • raf a lazy loaded requestAnimationFrame() polyfill.
  • caf a lazy loaded cancelAnimationFrame() polyfill.
• 2D Bounding Volumes
  • vec2Ext
  • rect (coords and size)
    • Basic
      • create(): rect
      • fromValues(x: number, y: number, width: number, height: number): rect
      • fromVectors(out: rect, coords: vec2, size: vec2): rect
      • clone(rect: rect): rect
      • copy(out: rect, rect: rect): rect
      • set(out: rect, x: number, y: number, width: number, height: number): rect
      • equals(a: rect, b: rect): rect
      • exactEquals(a: rect, b: rect): rect
      • contains(rect: rect, point: vec2): rect
      • getCenter(out: vec2, rect: rect): vec2
      • normalize(out: rect, rect: rect): rect
      • fromBox(out: rect, aabb: box2): rect
    • Edges
      • getLeft(rect: rect): number
      • getTop(rect: rect): number
      • getRight(rect: rect): number
      • getBottom(rect: rect): number
      • setLeft(out: rect, value: number): rect
      • setTop(out: rect, value: number): rect
      • setRight(out: rect, value: number): rect
      • setBottom(out: rect, value: number): rect
    • Corners
      • getTopLeft(out: vec2, rect: rect): vec2
      • getTopRight(out: vec2, rect: rect): vec2
      • getBottomLeft(out: vec2, rect: rect): vec2
      • getBottomRight(out: vec2, rect: rect): vec2
  • circle (coords and radius)
  • box2 (min, max)
  • obb2 (center, extent and rotation)
  • ray2 (origin and direction)
  • line2 (origin and normal)
  • segment2 (from point to point)
• 3D Bounding Volumes
  • vec3Ext
  • intersection3 (point and normal)
  • sphere (coords and radius)
    • Basic
      • create(): sphere
      • fromValues(x: number, y: number, radius: number): sphere
      • fromVectors(coords: vec3, radius: number): sphere
      • set(out: sphere, x: number, y: number, radius: number): sphere
      • setCoordsValues(out: sphere, x: number, y: number): sphere
      • setCoords(out: sphere, coords: vec3): sphere
      • getRadius(sphere: sphere): number
      • getCoords(out: vec3, sphere: sphere): vec3
      • setRadius(out: sphere, radius: number): sphere
      • clone(sphere: sphere): sphere
      • copy(out: sphere, sphere: sphere): sphere
      • equals(a: sphere, b: sphere): sphere
      • exactEquals(a: sphere, b: sphere): sphere
      • contains(sphere: sphere, point: vec3): sphere
    • Intersections
      • intersectSphere(sphere: sphere, other: sphere): boolean
      • intersectBOX3(sphere: sphere, aabb: box3): boolean
      • intersectOBX3(sphere: sphere, obb: obx3): boolean
      • intersectRay3(sphere: sphere, ray: ray3): boolean
      • intersectPlane(sphere: sphere, plane: plane): boolean
      • intersectLine3(sphere: sphere, line: line3): boolean
      • intersectSeg3(sphere: sphere, segment: seg3): boolean
    • Intersection details
      • getIntersectionSphere(out: intersection3, sphere: sphere, other: sphere): intersection3
      • getIntersectionBOX3(out: intersection3, sphere: sphere, aabb: box3): intersection3
      • getIntersectionOBB3(out: intersection3, sphere: sphere, obb: obb3): intersection3
      • getIntersectionRay3(out: intersection3, sphere: sphere, ray: ray3): intersection3
      • getIntersectionPlane(out: intersection3, sphere: sphere, plane: plane): intersection3
      • getIntersectionLine3(out: intersection3, sphere: sphere, line: line3): intersection3
      • getIntersectionSeg3(out: intersection3, sphere: sphere, segment: seg3): intersection3
  • box3 (min, max)
  • obb3 (center, extent and quaternion)
  • ray3 (origin and direction)
  • plane (origin and normal)
  • line3 (from point to point)
  • seg3 (from point to point)
  • frustum (considering)
  • transform (considering)
• Space partitioning (considering)
• Geometry utilities
  • calculateNormal(out: vec3, a: vec3, b: vec3, c: vec3): vec3
• Math functions and utilities
  • clamp(x: number, min: number, max: number): number
  • clampAB(x: number, a: number, b: number): number it's just clamp(x, Math.min(a, b), Math.max(a, b))
  • clamp01(x: number): number it's just clamp(x, 0, 1)
  • lerp(a: number, b: number, t: number): number
  • toDegrees(r: number): number
  • Math.hypot optional patch, that uses multiple implementations instead of single loop implementation, for argument counts of 0, 1, 2, 3, and 4, might be faster, but I use it in my code 🤷‍♂️