@swf2es/context3d 0.1.18 → 0.1.20

package/src/backend.ts

@@ -1,6 +1,26 @@
 import type { ProgramType } from "./agal.js";
 import type { DxtEncoder } from "./dxt.js";
 
+/**
+ * The widest and tallest back buffer configure() takes: Flash Player 32's and AIR 51's
+ * maxBackBufferWidth and maxBackBufferHeight on a desktop GPU, in every profile. A GPU that
+ * allows less still takes it, and draws it smaller (WebGLContext3D).
+ */
+export const MOST_BACK_BUFFER = 16384;
+
+/**
+ * A length in stage pixels at `scale` of the screen's to them, as AIR draws a back buffer
+ * configured for best resolution and its scissor rectangle: rounded half to even, as the
+ * FPU rounds by default (AIR 51 on Windows at 144 DPI: 33 to 50, 47 to 70).
+ */
+export function screenPixels(length: number, scale: number): number {
+  const exact = length * scale;
+  const floor = Math.floor(exact);
+  const rest = exact - floor;
+
+  return rest > 0.5 || (rest === 0.5 && floor % 2 !== 0) ? floor + 1 : floor;
+}
+
 export const COMPARE_MODES = [
   "always",
   "never",
@@ -53,10 +73,104 @@ export type SamplerFilter = (typeof SAMPLER_FILTERS)[number];
 export const SAMPLER_MIPS = ["mipnone", "mipnearest", "miplinear"] as const;
 export type SamplerMip = (typeof SAMPLER_MIPS)[number];
 
-/** The texture formats a backend stores: BGRA, and S3TC's DXT1 and DXT5 as Flash calls them. */
-export const TEXTURE_FORMATS = ["bgra", "compressed", "compressedAlpha"] as const;
+/**
+ * The texture formats a backend stores: BGRA, S3TC's DXT1 and DXT5 as Flash calls them,
+ * 16-bit 5:6:5 colour and 4:4:4:4 colour with alpha, and RGBA in half floats.
+ */
+export const TEXTURE_FORMATS = [
+  "bgra",
+  "compressed",
+  "compressedAlpha",
+  "bgrPacked565",
+  "bgraPacked4444",
+  "rgbaHalfFloat",
+] as const;
 export type TextureFormat = (typeof TEXTURE_FORMATS)[number];
 
+/** Bytes a texel of each uncompressed format takes, as its byte uploads give it. */
+export const TEXEL_BYTES: Partial<Record<TextureFormat, number>> = {
+  bgra: 4,
+  bgrPacked565: 2,
+  bgraPacked4444: 2,
+  rgbaHalfFloat: 8,
+};
+
+/** Whether a format holds S3TC blocks, which no draw renders into. */
+export function compressedFormat(format: TextureFormat): boolean {
+  return format === "compressed" || format === "compressedAlpha";
+}
+
+/** Stage3D's profiles, from what the least GPU does to the most. */
+export const PROFILES = [
+  "baselineConstrained",
+  "baseline",
+  "baselineExtended",
+  "standardConstrained",
+  "standard",
+  "standardExtended",
+] as const;
+export type Profile = (typeof PROFILES)[number];
+
+/** What a profile allows, as AIR 51 grants it on a desktop GPU (docs/architecture/rendering.md). */
+export interface ProfileLimits {
+  /** The newest AGAL version its programs may be. */
+  readonly agal: number;
+  /** The widest and tallest Texture. */
+  readonly textureSize: number;
+  /** The widest and tallest RectangleTexture, 0 where the profile has none. */
+  readonly rectangleSize: number;
+  /** Whether it creates rgbaHalfFloat textures. */
+  readonly halfFloat: boolean;
+  /** How many textures a draw renders into at once. */
+  readonly colorOutputs: number;
+}
+
+const LIMITS: Record<Profile, ProfileLimits> = {
+  baselineConstrained: {
+    agal: 1,
+    textureSize: 2048,
+    rectangleSize: 0,
+    halfFloat: false,
+    colorOutputs: 1,
+  },
+  baseline: { agal: 1, textureSize: 2048, rectangleSize: 2048, halfFloat: false, colorOutputs: 1 },
+  baselineExtended: {
+    agal: 1,
+    textureSize: 4096,
+    rectangleSize: 4096,
+    halfFloat: false,
+    colorOutputs: 1,
+  },
+  standardConstrained: {
+    agal: 2,
+    textureSize: 4096,
+    rectangleSize: 4096,
+    halfFloat: true,
+    colorOutputs: 1,
+  },
+  standard: { agal: 2, textureSize: 4096, rectangleSize: 4096, halfFloat: true, colorOutputs: 4 },
+  standardExtended: {
+    agal: 3,
+    textureSize: 4096,
+    rectangleSize: 4096,
+    halfFloat: true,
+    colorOutputs: 4,
+  },
+};
+
+export function profileLimits(profile: Profile): ProfileLimits {
+  return LIMITS[profile];
+}
+
+/** Cube faces are at most this wide in every profile. */
+export const MOST_CUBE = 1024;
+
+/** Sampler, vertex attribute and constant registers a context holds in every profile. */
+export const SAMPLER_SLOTS = 16;
+export const VERTEX_SLOTS = 16;
+export const VERTEX_CONSTANTS = 250;
+export const FRAGMENT_CONSTANTS = 200;
+
 export const VERTEX_FORMATS = ["float1", "float2", "float3", "float4", "bytes4"] as const;
 export type VertexFormat = (typeof VERTEX_FORMATS)[number];
 
@@ -77,7 +191,8 @@ export class TextureBindingError extends Error {
     | "wrap"
     | "rectangleMip"
     | "feedback"
-    | "format";
+    | "format"
+    | "streaming";
 
   /** The sampler it names, where it names one. */
   readonly sampler: number;
@@ -100,6 +215,10 @@ export interface Buffer3D {
 }
 
 export interface Program3D {
+  /** The colour outputs its fragment program writes, 1 to 4; 1 before an upload. */
+  readonly outputs: number;
+  /** The vertex attributes it reads, a bit each; 0 before an upload. */
+  readonly attributes: number;
   upload(vertex: Uint8Array, fragment: Uint8Array): void;
   dispose(): void;
 }
@@ -110,6 +229,11 @@ export interface Texture3D {
   readonly levels: number;
   readonly cube: boolean;
   readonly rectangle: boolean;
+  /**
+   * createTexture's streamingLevels: the levels from it to the smallest are enough to draw it
+   * with mip filtering, from the finest of them uploaded, as AIR draws a texture still loading.
+   */
+  readonly streaming: number;
   /** What samplers must read it as; a compressed texture also takes pixels, as AIR's do. */
   readonly format: TextureFormat;
   /** Top-down premultiplied ARGB pixels, copied before returning.
@@ -140,6 +264,11 @@ export interface Context3DLifecycle {
 /** Loss callbacks are asynchronous. Keep the lost surface until remove(), including
  * its restoration listener; remove() must detach both listeners before releasing it. */
 export interface Stage3DHost {
+  /**
+   * What a request waits for before create(): a host that loads its backend at the first
+   * request gives the load, null once loaded. A rejection makes the context unavailable (#3702).
+   */
+  ready?(): Promise<unknown> | null;
   create(slot: number, lifecycle: Context3DLifecycle): Context3D;
   place(slot: number, x: number, y: number, visible: boolean): void;
   remove(slot: number): void;
@@ -154,9 +283,24 @@ export interface Context3D {
    * format (TextureBindingError "format"): AIR checks from SWF 17 on.
    */
   samplerFormats: boolean;
+  /** The profile it was made for: what its programs, textures and targets may be. */
+  profile: Profile;
   /** Optional acceleration for pixels uploaded to compressed textures. */
   setDxtEncoder?(encoder: DxtEncoder): void;
-  configure(width: number, height: number, depth?: boolean, antiAlias?: number): void;
+  /**
+   * Width and height from 32 to MOST_BACK_BUFFER, in the back buffer's pixels. `scale` is
+   * those to a CSS pixel where it shows, and to a scissor rectangle's unit: a back buffer
+   * configured for best resolution has the stage's contentsScaleFactor, any other 1.
+   */
+  configure(
+    width: number,
+    height: number,
+    depth?: boolean,
+    antiAlias?: number,
+    scale?: number,
+  ): void;
+  /** No back buffer, width and height 0, as a size configureBackBuffer refuses leaves AIR's. */
+  unconfigure(): void;
   clear(
     red: number,
     green: number,
@@ -180,10 +324,18 @@ export interface Context3D {
   setColorMask(red: boolean, green: boolean, blue: boolean, alpha: boolean): void;
   /** Null disables clipping; coordinates are in top-down target pixels. */
   setScissor(x: number | null, y?: number, width?: number, height?: number): void;
-  createBuffer(count: number, stride: number): Buffer3D;
+  /** `stride` 32-bit values a vertex, or 0 for 16-bit indices; `dynamic` for data uploaded often. */
+  createBuffer(count: number, stride: number, dynamic?: boolean): Buffer3D;
   createProgram(): Program3D;
-  createTexture(width: number, height: number, cube?: boolean, format?: TextureFormat): Texture3D;
-  createRectangleTexture(width: number, height: number): Texture3D;
+  /** `streaming` from 0 to the texture's levels less one. */
+  createTexture(
+    width: number,
+    height: number,
+    cube?: boolean,
+    format?: TextureFormat,
+    streaming?: number,
+  ): Texture3D;
+  createRectangleTexture(width: number, height: number, format?: TextureFormat): Texture3D;
   /** Level-zero target; face selects a cube surface. Null resumes the back buffer. */
   setRenderTarget(
     texture: Texture3D | null,
@@ -191,6 +343,11 @@ export interface Context3D {
     face?: number,
     antiAlias?: number,
   ): void;
+  /**
+   * Colour output `index`, 1 to 3, draws into `texture` (`face` of a cube) beside
+   * setRenderTarget's; null stops it. The texture's size and format are the target's.
+   */
+  setColorOutput(index: number, texture: Texture3D | null, face?: number): void;
   setSampler(index: number, wrap: SamplerWrap, filter: SamplerFilter, mip: SamplerMip): void;
   setTexture(index: number, texture: Texture3D | null): void;
   setProgram(program: Program3D): void;

package/src/errors.ts

@@ -56,7 +56,33 @@ export type Context3DErrorReason =
   | "agalDiscard"
   | "agalMask"
   | "agalReserved"
-  | "agalSampler";
+  | "agalSampler"
+  | "agalProfileVersion"
+  | "agalOpcodeRange"
+  | "agalOpcodeVersion"
+  | "agalFragmentOnly"
+  | "agalSamplerStage"
+  | "agalElse"
+  | "agalEndIf"
+  | "agalEmptyBranch"
+  | "agalConditionDestination"
+  | "agalScalar"
+  | "agalNesting"
+  | "agalConditionOutput"
+  | "agalConditionTexture"
+  | "agalDepthStage"
+  | "agalDepthIndex"
+  | "agalDepthMask"
+  | "agalInstanceStage"
+  | "agalOutputTwice"
+  | "agalOutputSlots"
+  | "agalConditionDerivative"
+  | "agalConstants"
+  | "agalNativeLength"
+  | "agalSamplerIndex"
+  | "agalSamplerDimension"
+  | "agalSamplerMip"
+  | "agalSamplerFilter";
 
 export class Context3DError extends Error {
   readonly reason: Context3DErrorReason;

package/src/index.ts

@@ -1,4 +1,4 @@
-/** Experimental renderer contracts and AGAL v1 translation, without browser dependencies. */
+/** Stage3D's renderer contracts and AGAL translation, without browser dependencies. */
 
 export { type ProgramType, type SamplerSource, type ShaderSource, translate } from "./agal.js";
 export {
@@ -11,9 +11,18 @@ export {
   type Context3DLifecycle,
   CULL_FACES,
   type CullFace,
+  compressedFormat,
+  FRAGMENT_CONSTANTS,
+  MOST_BACK_BUFFER,
+  MOST_CUBE,
+  PROFILES,
+  type Profile,
+  type ProfileLimits,
   type Program3D,
+  profileLimits,
   SAMPLER_FILTERS,
   SAMPLER_MIPS,
+  SAMPLER_SLOTS,
   SAMPLER_WRAPS,
   SamplerBiasError,
   type SamplerFilter,
@@ -23,11 +32,15 @@ export {
   STENCIL_ACTIONS,
   type Stage3DHost,
   type StencilAction,
+  screenPixels,
+  TEXEL_BYTES,
   TEXTURE_FORMATS,
   type Texture3D,
   TextureBindingError,
   type TextureFormat,
+  VERTEX_CONSTANTS,
   VERTEX_FORMATS,
+  VERTEX_SLOTS,
   type VertexFormat,
   VertexOffsetError,
 } from "./backend.js";