chorama 0.0.0

package/src/texture/sampler.js

@@ -0,0 +1,111 @@
+import { TextureFilter, TextureWrap } from '../constants/index.js'
+import { CompareFunction } from '../core/index.js'
+export class Sampler {
+  /**
+   * @type {TextureFilter}
+   */
+
+  magnificationFilter
+  /**
+   * @type {TextureFilter}
+   */
+  minificationFilter
+  /**
+   * @type {TextureFilter | undefined}
+   */
+  mipmapFilter
+  
+  /**
+   * @type {TextureWrap}
+   */
+  wrapS
+  /**
+   * @type {TextureWrap}
+   */
+  wrapT
+  /**
+   * @type {TextureWrap}
+   */
+  wrapR
+  /**
+   * @type {number}
+   */
+  anisotropy
+  /**
+   * @type {SamplerLODSettings}
+   */
+  lod
+  /**
+   * @type {CompareFunction | undefined}
+   */
+  compare
+  /**
+   * @param {SamplerSettings} settings 
+   */
+  constructor({
+    magnificationFilter = Sampler.defaultSettings.magnificationFilter,
+    minificationFilter = Sampler.defaultSettings.minificationFilter,
+    mipmapFilter = Sampler.defaultSettings.mipmapFilter,
+    wrapS = Sampler.defaultSettings.wrapS,
+    wrapT = Sampler.defaultSettings.wrapT,
+    wrapR = Sampler.defaultSettings.wrapR,
+    lod = Sampler.defaultSettings.lod,
+    anisotropy = Sampler.defaultSettings.anisotropy,
+    compare = Sampler.defaultSettings.compare
+  } = Sampler.defaultSettings) {
+    this.minificationFilter = minificationFilter
+    this.magnificationFilter = magnificationFilter
+    this.mipmapFilter = mipmapFilter
+    this.wrapS = wrapS
+    this.wrapT = wrapT
+    this.wrapR = wrapR
+    this.anisotropy = anisotropy
+    this.lod = lod
+    this.compare = compare
+  }
+
+  static default(){
+    return new Sampler()
+  }
+
+  /**
+   * @readonly
+   * @type {Readonly<
+   *   Required<Omit<SamplerSettings,'compare' | 'mipmapFilter'>>
+   *   > & {
+   *    compare: CompareFunction | undefined;
+   *    mipmapFilter: TextureFilter | undefined;
+   *   }
+   * }
+   */
+  static defaultSettings = {
+    magnificationFilter: TextureFilter.Linear,
+    minificationFilter: TextureFilter.Linear,
+    mipmapFilter: undefined,
+    wrapS: TextureWrap.Clamp,
+    wrapT: TextureWrap.Clamp,
+    wrapR: TextureWrap.Clamp,
+    lod: { min: 0, max: 12 },
+    anisotropy: 1,
+    compare: undefined
+  }
+}
+
+/**
+ * @typedef SamplerSettings
+ * @property {TextureFilter} [minificationFilter]
+ * @property {TextureFilter} [magnificationFilter]
+ * @property {TextureFilter} [mipmapFilter]
+ * @property {TextureWrap} [wrapS]
+ * @property {TextureWrap} [wrapT]
+ * @property {TextureWrap} [wrapR]
+ * @property {SamplerLODSettings} [lod]
+ * @property {number} [anisotropy]
+ * @property {CompareFunction} [compare]
+ */
+
+/**
+ * @typedef SamplerLODSettings
+ * @property {number} max
+ * @property {number} min
+ */

package/src/texture/texture.js

@@ -0,0 +1,234 @@
+import { TextureFormat, TextureType } from "../constants/index.js"
+
+export class Texture {
+
+  /**
+   * Tracks if the texture has changed since last checked.
+   * @type {boolean}
+   */
+  #changed = false
+
+  /**
+   * The raw pixel data for the texture.
+   * @type {ArrayBuffer | undefined}
+   */
+  #data
+
+  /**
+   * The width of the texture in pixels.
+   * @type {number}
+   */
+  #width
+
+  /**
+   * The height of the texture in pixels.
+   * @type {number}
+   */
+  #height
+
+  /**
+   * The depth of the texture, used for 3D textures or texture arrays.
+   * @type {number}
+   */
+  #depth
+
+  /**
+   * The texture format of this texture.
+   * @type {TextureFormat}
+   */
+  #format
+
+  /**
+   * Whether mipmaps should be automatically generated for this texture.
+   * @type {boolean}
+   */
+  #generateMipmaps
+
+  /**
+   * Whether the texture should be flipped vertically on upload.
+   * @type {boolean}
+   */
+  #flipY
+
+  /**
+   * The type of texture (e.g., Texture2D, TextureCube, etc.).
+   * @type {TextureType}
+   */
+  #type
+
+  /**
+   * @param {TextureSettings & { data?: ArrayBuffer, type: TextureType }} settings
+   */
+  constructor({
+    data,
+    type,
+    format = Texture.defaultSettings.format,
+    generateMipmaps = Texture.defaultSettings.generateMipmaps,
+    flipY = Texture.defaultSettings.flipY,
+    width = Texture.defaultSettings.width,
+    height = Texture.defaultSettings.height,
+    depth = Texture.defaultSettings.depth,
+  }) {
+    this.#data = data
+    this.#type = type
+    this.#width = width
+    this.#height = height
+    this.#depth = depth
+    this.#flipY = flipY
+    this.#format = format
+    this.#generateMipmaps = generateMipmaps
+  }
+
+  /**
+   * @package
+   * @returns {boolean}
+   * This is an internal property, do not use!
+   */
+  get changed() {
+    const previous = this.#changed
+    this.#changed = false
+    return previous
+  }
+
+  /** @type {ArrayBuffer | undefined} */
+  get data() { return this.#data }
+  set data(value) {
+    this.#data = value
+    this.#changed = true
+  }
+
+  /** @type {number} */
+  get width() { return this.#width }
+  set width(value) {
+    this.#width = value
+    this.#changed = true
+  }
+
+  /** @type {number} */
+  get height() { return this.#height }
+  set height(value) {
+    this.#height = value
+    this.#changed = true
+  }
+
+  /** @type {number} */
+  get depth() { return this.#depth }
+  set depth(value) {
+    this.#depth = value
+    this.#changed = true
+  }
+
+  /** @type {TextureFormat} */
+  get format() { return this.#format }
+  set format(value) {
+    this.#format = value
+    this.#changed = true
+  }
+
+  /** @type {boolean} */
+  get generateMipmaps() { return this.#generateMipmaps }
+  set generateMipmaps(value) {
+    this.#generateMipmaps = value
+    this.#changed = true
+  }
+
+  /** @type {boolean} */
+  get flipY() { return this.#flipY }
+  set flipY(value) {
+    this.#flipY = value
+    this.#changed = true
+  }
+
+  /** @type {TextureType} */
+  get type() { return this.#type }
+  set type(value) {
+    this.#type = value
+    this.#changed = true
+  }
+
+  /**
+   * Applies a new set of texture settings.
+   * @param {TextureSettings} settings
+   */
+  apply({
+    format = Texture.defaultSettings.format,
+    generateMipmaps = Texture.defaultSettings.generateMipmaps,
+    flipY = Texture.defaultSettings.flipY,
+    width = Texture.defaultSettings.width,
+    height = Texture.defaultSettings.height,
+    depth = Texture.defaultSettings.depth,
+  }) {
+    this.width = width
+    this.height = height
+    this.depth = depth
+    this.flipY = flipY
+    this.format = format
+    this.generateMipmaps = generateMipmaps
+  }
+
+  /**
+   * Copies the values from another texture into this one.
+   * @param {this} other
+   * @returns {this}
+   */
+  copy(other) {
+    this.data = other.data ? other.data.slice() : undefined
+    this.format = other.format
+    this.width = other.width
+    this.height = other.height
+    this.depth = other.depth
+    this.type = other.type
+    this.flipY = other.flipY
+    this.generateMipmaps = other.generateMipmaps
+    return this
+  }
+
+  /**
+   * Creates a new texture that is a copy of this one.
+   * @returns {this}
+   */
+  clone() {
+    return new /** @type {new (...args:any[]) => this} */(this.constructor)({}).copy(this)
+  }
+
+  /**
+   * Creates a default 1×1 white texture.
+   * @returns {Texture}
+   */
+  static default() {
+    const width = 1
+    const height = 1
+    const pixel = new Uint8Array([255, 255, 255, 255])
+    const texture = new Texture({
+      width,
+      height,
+      data: pixel.buffer,
+      type: TextureType.Texture2D,
+    })
+    return texture
+  }
+
+  /**
+   * Default texture settings.
+   * @readonly
+   * @type {Readonly<Required<TextureSettings>>}
+   */
+  static defaultSettings = {
+    format: TextureFormat.RGBA8Unorm,
+    generateMipmaps: false,
+    flipY: false,
+    width: 0,
+    height: 0,
+    depth: 1,
+  }
+}
+
+/**
+ * @typedef TextureSettings
+ * @property {boolean} [generateMipmaps=true]
+ * @property {TextureFormat} [format]
+ * @property {boolean} [flipY]
+ * @property {number} [width]
+ * @property {number} [height]
+ * @property {number} [depth]
+ */

package/src/utils/index.js

@@ -0,0 +1,115 @@
+import { Vector2 } from "../math/index.js"
+
+export class ViewRectangle {
+  offset = new Vector2()
+  size = new Vector2(1, 1)
+
+  /**
+   * @param {ViewRectangle} other
+   */
+  copy(other) {
+    this.offset.copy(other.offset)
+    this.size.copy(other.size)
+  }
+
+  clone() {
+    return new ViewRectangle().copy(this)
+  }
+}
+
+export class Range {
+  start
+  end
+  constructor(start = 0, end = 1) {
+    this.start = start
+    this.end = end
+  }
+
+  /**
+   * @param {Range} other
+   */
+  copy(other) {
+    this.start = other.start
+    this.end = other.end
+  }
+
+  clone() {
+    return new Range().copy(this)
+  }
+}
+
+/**
+ * Throws an error if the supplied test is null or undefined.
+ *
+ * @template T
+ * @param {T} test
+ * @param {string} message
+ * @returns {asserts test is NonNullable<T>}
+ */
+export function assert(test, message) {
+  if (test === undefined || test === null) throw message
+}
+
+/**
+ * @template T
+ * @template {string} U
+ * @typedef {T & {__brand: U;}} Brand
+ */
+
+/**
+ * @param {ArrayBufferLike} source
+ * @param {ArrayBufferLike} destination
+ * @param {number | undefined} offset
+ * @param {number | undefined} length
+ */
+export function copyBuffer(source, destination, offset, length) {
+  const sourceView = new Uint8Array(source)
+  const destView = new Uint8Array(destination, offset, length)
+  destView.set(sourceView)
+}
+
+export class AbstractClassError {
+  static Unconstructable = "The class `{0}` is not constructible.Extend the class."
+  static MethodUnimplemented = "The method `{0}.{1}()` is not implemented. Override the method without using `super.{1}()`."
+  static MethodUncallable = "The method `{0}.{1}()` is not callable.`{0}` is an abstract class."
+}
+
+/**
+ * @param {string} string
+ * @param {string[]} args
+ */
+export function formatString(string, ...args) {
+  return string.replace(/{(\d+)}/g, function (match, number) {
+    const index = parseInt(number)
+    if (typeof index == 'number') {
+      return args[index] || match
+    }
+
+    return match
+  })
+}
+
+/**
+ * @param {object} item
+ * @param {object} baseConstructor
+ * @param {string} methodName
+ * @returns {never}
+ */
+export function abstractMethod(item, baseConstructor, methodName) {
+  if (item.constructor === baseConstructor) {
+    throw formatString(AbstractClassError.MethodUncallable, item.constructor.name, methodName)
+  }
+  throw formatString(AbstractClassError.MethodUnimplemented, item.constructor.name, methodName)
+}
+
+/**
+ * 
+ * @param {object} item 
+ * @param {object} baseConstructor 
+ * @returns {never | void}
+ */
+export function abstractClass(item, baseConstructor) {
+  if(item.constructor === baseConstructor){
+    throw formatString(AbstractClassError.Unconstructable, item.constructor.name)
+  }
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "files": [],
+  "references": [
+    {
+      "path": "./.configs/tsconfig.lib.json"
+    },
+    {
+      "path": "./.configs/tsconfig.website.json"
+    }
+  ]
+}

package/website/config/index.ts

@@ -0,0 +1 @@
+export * from './navigation'

package/website/config/navigation.ts

@@ -0,0 +1,53 @@
+import { withBase } from "../utils/url";
+
+export interface NavTab {
+  label: string;
+  href?: string;
+  children?: NavTab[];
+}
+
+const tabs: NavTab[] = [
+  {
+    label: "Introduction",
+    href: "#chorama",
+    children: [
+      { label: "Top", href: "#chorama" },
+      { label: "Features", href: "#features" },
+      { label: "Who This Is For", href: "#who-this-is-for" },
+      { label: "Getting Started", href: "#getting-started" },
+      { label: "Core Usage Flow", href: "#core-usage-flow" }
+    ]
+  },
+  {
+    label: "Guide",
+    href: "/guide",
+    children: [
+      { label: "Overview", href: "/guide" },
+      { label: "Installation", href: "/guide/installation" },
+      { label: "First Scene", href: "/guide/first-scene" },
+      { label: "Camera and Controls", href: "/guide/camera-and-controls" },
+      { label: "Materials and Lighting", href: "/guide/materials-and-lighting" },
+      { label: "Textures and Assets", href: "/guide/textures-and-assets" },
+      { label: "Render Targets and Views", href: "/guide/render-targets-and-views" },
+      { label: "Scene Graph and Transforms", href: "/guide/scene-graph-and-transforms" },
+      { label: "Plugins and Render Pipeline", href: "/guide/plugins-and-render-pipeline" },
+      { label: "API Map", href: "/guide/api-map" },
+      { label: "Troubleshooting", href: "/guide/troubleshooting" }
+    ]
+  },
+  {
+    label: "Examples",
+    href: "/examples",
+    children: [{ label: "Overview", href: "/examples" }]
+  }
+];
+
+function mapTabLinks(tab: NavTab): NavTab {
+  return {
+    ...tab,
+    href: tab.href ? withBase(tab.href) : undefined,
+    children: tab.children?.map(mapTabLinks),
+  };
+}
+
+export const sidebarTabs: NavTab[] = tabs.map(mapTabLinks);

package/website/content.config.ts

@@ -0,0 +1,92 @@
+import { defineCollection, z } from "astro:content";
+import { glob } from "astro/loaders";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+const examplesRoot = path.resolve("./examples");
+
+interface ExampleEntry {
+  id: string;
+  title: string;
+  description: string;
+  category: string;
+  filePath: string;
+  source: string;
+}
+
+function toTitle(value: string): string {
+  return value
+    .replace(/[_-]+/g, " ")
+    .replace(/\b\w/g, (match) => match.toUpperCase());
+}
+
+async function collectExampleFiles(dir: string, root: string): Promise<string[]> {
+  const dirEntries = await readdir(dir, { withFileTypes: true });
+  const files: string[] = [];
+
+  for (const dirEntry of dirEntries) {
+    const fullPath = path.join(dir, dirEntry.name);
+    const relativePath = path.relative(root, fullPath).split(path.sep).join("/");
+
+    if (dirEntry.isDirectory()) {
+      if (relativePath === "addons" || relativePath.startsWith("addons/")) {
+        continue;
+      }
+      files.push(...(await collectExampleFiles(fullPath, root)));
+      continue;
+    }
+
+    if (dirEntry.isFile() && dirEntry.name.endsWith(".js")) {
+      files.push(path.relative(root, fullPath));
+    }
+  }
+
+  return files;
+}
+
+const examples = defineCollection({
+  loader: async (): Promise<ExampleEntry[]> => {
+    const relativePaths = await collectExampleFiles(examplesRoot, examplesRoot);
+
+    return Promise.all(
+      relativePaths.map(async (relativePath) => {
+        const normalizedPath = relativePath.split(path.sep).join("/");
+        const id = normalizedPath.replace(/\.js$/, "");
+        const segments = id.split("/");
+        const category = segments[0] || "uncategorized";
+        const fileName = segments.at(-1) || "example";
+
+        return {
+          id,
+          title: toTitle(fileName),
+          description: `${toTitle(category)} example`,
+          category,
+          filePath: `/examples/${normalizedPath}`,
+          source: await readFile(path.join(examplesRoot, relativePath), "utf-8")
+        };
+      })
+    );
+  },
+  schema: z.object({
+    title: z.string(),
+    description: z.string(),
+    category: z.string(),
+    filePath: z.string(),
+    source: z.string()
+  })
+});
+
+const guide = defineCollection({
+  loader: glob({
+    pattern: "**/*.md",
+    base: "./content/guide"
+  }),
+  schema: z.object({
+    title: z.string()
+  })
+});
+
+export const collections = {
+  examples,
+  guide
+};