@egret/contracts 7.0.1-rc.3 → 7.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,4 +1,5 @@
1
1
  declare const imageData2DBrand: unique symbol;
2
+ /** The size and pixels of an image to copy: sRGB RGBA, eight bits a channel, rows top to bottom. */
2
3
  export interface ImageData2DInput {
3
4
  readonly width: number;
4
5
  readonly height: number;
@@ -20,12 +21,14 @@ export interface ImageData2D {
20
21
  readonly alphaMode: 'straight';
21
22
  readonly origin: 'top-left';
22
23
  }
24
+ /** A rectangle of an image in whole pixels, from its top left corner. */
23
25
  export interface TextureRegion2D {
24
26
  readonly x: number;
25
27
  readonly y: number;
26
28
  readonly width: number;
27
29
  readonly height: number;
28
30
  }
31
+ /** The largest image accepted: its longest edge and its number of pixels. */
29
32
  export declare const IMAGE_LIMITS_2D: Readonly<{
30
33
  readonly maxSourceEdge: 4096;
31
34
  readonly maxSourcePixels: 4194304;
@@ -36,8 +39,11 @@ export declare const IMAGE_LIMITS_2D: Readonly<{
36
39
  readonly maxImageScratchBytes: 33554432;
37
40
  readonly maxPendingTextureBytes: 33554432;
38
41
  }>;
42
+ /** Copies the pixels into an image this module owns; a wrong size or pixel count is refused with a TypeError. */
39
43
  export declare function createImageData2D(input: ImageData2DInput): ImageData2D;
44
+ /** Whether a value is an image made by `createImageData2D`, without reading any of its properties. */
40
45
  export declare function isImageData2D(value: unknown): value is ImageData2D;
46
+ /** A fresh copy of an image's pixels, which the caller owns. */
41
47
  export declare function copyImageData2DPixels(image: ImageData2D): Uint8Array<ArrayBuffer>;
42
48
  export {};
43
49
  //# sourceMappingURL=ImageData2D.d.ts.map
@@ -20,6 +20,7 @@ const weakHas = WeakMap.prototype.has;
20
20
  const weakGet = WeakMap.prototype.get;
21
21
  const weakSet = WeakMap.prototype.set;
22
22
  const owned = new WeakMap();
23
+ /** The largest image accepted: its longest edge and its number of pixels. */
23
24
  export const IMAGE_LIMITS_2D = freeze({
24
25
  // One image is at most 2048 x 2048 pixels, or any other shape of that area within the edge bound.
25
26
  maxSourceEdge: 4096,
@@ -56,6 +57,7 @@ function cloneBytes(source, length) {
56
57
  apply(setBytes, result, [source]);
57
58
  return result;
58
59
  }
60
+ /** Copies the pixels into an image this module owns; a wrong size or pixel count is refused with a TypeError. */
59
61
  export function createImageData2D(input) {
60
62
  if (typeof input !== 'object' || input === null)
61
63
  throw new TypeFault('Image descriptor must be an object');
@@ -116,9 +118,11 @@ export function createImageData2D(input) {
116
118
  apply(weakSet, owned, [image, copy]);
117
119
  return image;
118
120
  }
121
+ /** Whether a value is an image made by `createImageData2D`, without reading any of its properties. */
119
122
  export function isImageData2D(value) {
120
123
  return typeof value === 'object' && value !== null && apply(weakHas, owned, [value]);
121
124
  }
125
+ /** A fresh copy of an image's pixels, which the caller owns. */
122
126
  export function copyImageData2DPixels(image) {
123
127
  // Identity authentication performs no property reads on forged/proxied values.
124
128
  if (!isImageData2D(image))
@@ -7,12 +7,14 @@ export interface Matrix2D {
7
7
  readonly tx: number;
8
8
  readonly ty: number;
9
9
  }
10
+ /** An axis-aligned rectangle in its own coordinate space. */
10
11
  export interface Rectangle2D {
11
12
  readonly x: number;
12
13
  readonly y: number;
13
14
  readonly width: number;
14
15
  readonly height: number;
15
16
  }
17
+ /** A clip rectangle together with the matrix that places it on the frame. */
16
18
  export interface ClipRectangle2D {
17
19
  readonly matrix: Matrix2D;
18
20
  readonly rect: Rectangle2D;
@@ -1,6 +1,9 @@
1
1
  declare const sharedGeometry2DBrand: unique symbol;
2
+ /** A float array of a shared geometry, in single or double precision. */
2
3
  export type SharedFloatArray2D = Float32Array<ArrayBuffer> | Float64Array<ArrayBuffer>;
4
+ /** An index array of a shared geometry, in 16 or 32 bits. */
3
5
  export type SharedIndexArray2D = Uint16Array<ArrayBuffer> | Uint32Array<ArrayBuffer>;
6
+ /** The positions, texture coordinates, light and dark colors and triangle indices of a mesh to share with a renderer. */
4
7
  export interface SharedGeometryInput2D {
5
8
  readonly positions: SharedFloatArray2D;
6
9
  readonly uvs: SharedFloatArray2D;
@@ -21,6 +24,7 @@ export interface SharedGeometry2D {
21
24
  readonly darkColors: readonly number[];
22
25
  readonly indices: readonly number[];
23
26
  }
27
+ /** Copies and checks a mesh into a shared geometry that renderers can draw; malformed arrays are refused. */
24
28
  export declare function createSharedGeometry2D(input: SharedGeometryInput2D): SharedGeometry2D;
25
29
  export declare function isSharedGeometry2D(value: unknown): value is SharedGeometry2D;
26
30
  export {};
@@ -105,6 +105,7 @@ function canonical(source, length, kind, vertexCount) {
105
105
  setPrototypeOf(output, arrayPrototype);
106
106
  return freeze(output);
107
107
  }
108
+ /** Copies and checks a mesh into a shared geometry that renderers can draw; malformed arrays are refused. */
108
109
  export function createSharedGeometry2D(input) {
109
110
  if (typeof input !== 'object' || input === null)
110
111
  throw new TypeFault('Shared geometry descriptor must be an object');
@@ -4,6 +4,9 @@ type Domain = 'page' | 'region';
4
4
  type Filter = 'nearest' | 'linear';
5
5
  type Address = 'clamp-to-edge' | 'repeat' | 'mirror-repeat';
6
6
  type Isolation = 'bounded' | 'strict';
7
+ /** `linear` samples a texture drawn smaller than it is from its smaller copies, blended between the two nearest. */
8
+ type MipmapFilter = 'none' | 'linear';
9
+ /** The colors, blend, sampling and addressing of a material for shared meshes, as plain values to check. */
7
10
  export interface SharedMaterialInput2D {
8
11
  readonly light?: readonly number[] | undefined;
9
12
  readonly dark?: readonly number[] | undefined;
@@ -17,7 +20,9 @@ export interface SharedMaterialInput2D {
17
20
  readonly minFilter?: Filter | undefined;
18
21
  readonly magFilter?: Filter | undefined;
19
22
  readonly maxAnisotropy?: number | undefined;
23
+ readonly mipmapFilter?: MipmapFilter | undefined;
20
24
  }
25
+ /** A checked material for shared meshes; only `createSharedMaterial2D` makes one. */
21
26
  export interface SharedMaterial2D {
22
27
  readonly [sharedMaterial2DBrand]: true;
23
28
  readonly light: readonly [number, number, number, number];
@@ -32,7 +37,9 @@ export interface SharedMaterial2D {
32
37
  readonly minFilter: Filter;
33
38
  readonly magFilter: Filter;
34
39
  readonly maxAnisotropy: 1;
40
+ readonly mipmapFilter: MipmapFilter;
35
41
  }
42
+ /** Checks and freezes a material for shared meshes; values out of range are refused. */
36
43
  export declare function createSharedMaterial2D(input: SharedMaterialInput2D): SharedMaterial2D;
37
44
  export declare function isSharedMaterial2D(value: unknown): value is SharedMaterial2D;
38
45
  export {};
@@ -71,11 +71,12 @@ function address(value) {
71
71
  }
72
72
  return value;
73
73
  }
74
+ /** Checks and freezes a material for shared meshes; values out of range are refused. */
74
75
  export function createSharedMaterial2D(input) {
75
76
  if (typeof input !== 'object' || input === null || isArray(input)) {
76
77
  throw new TypeFault('Shared material descriptor must be a record');
77
78
  }
78
- // Complete the twelve top-level reads before examining either tuple.
79
+ // Complete the thirteen top-level reads before examining either tuple.
79
80
  const lightInput = read(input, 'light');
80
81
  const darkInput = read(input, 'dark');
81
82
  const blendInput = read(input, 'blend');
@@ -88,6 +89,7 @@ export function createSharedMaterial2D(input) {
88
89
  const minInput = read(input, 'minFilter');
89
90
  const magInput = read(input, 'magFilter');
90
91
  const anisotropyInput = read(input, 'maxAnisotropy');
92
+ const mipmapInput = read(input, 'mipmapFilter');
91
93
  if (lightInput !== undefined)
92
94
  tupleBrand(lightInput);
93
95
  if (darkInput !== undefined)
@@ -148,6 +150,12 @@ export function createSharedMaterial2D(input) {
148
150
  }
149
151
  if (maxAnisotropy !== 1)
150
152
  throw new TypeFault('Shared material option is unsupported');
153
+ const mipmapFilter = mipmapInput === undefined ? 'none' : mipmapInput;
154
+ if (mipmapFilter !== 'none' && mipmapFilter !== 'linear')
155
+ throw new TypeFault('Shared material option is unsupported');
156
+ // Smaller copies are blended, so they need the linear filter that blends the texels of each.
157
+ if (mipmapFilter === 'linear' && selectedFilter !== 'linear')
158
+ throw new TypeFault('Shared material option is unsupported');
151
159
  if (minFilter !== selectedFilter ||
152
160
  magFilter !== selectedFilter ||
153
161
  (samplingDomain === 'region' && (addressU !== 'clamp-to-edge' || addressV !== 'clamp-to-edge')) ||
@@ -168,7 +176,8 @@ export function createSharedMaterial2D(input) {
168
176
  mipLevel: 0,
169
177
  minFilter,
170
178
  magFilter,
171
- maxAnisotropy: 1
179
+ maxAnisotropy: 1,
180
+ mipmapFilter
172
181
  });
173
182
  apply(weakSet, owned, [material, true]);
174
183
  return material;
@@ -5,9 +5,19 @@ import type { TexturedGeometry2D } from './TexturedGeometry2D.js';
5
5
  import type { SharedGeometry2D } from './SharedGeometry2D.js';
6
6
  import type { SharedMaterial2D } from './SharedMaterial2D.js';
7
7
  import type { TextureViewRegion2D } from './TextureViewRegion2D.js';
8
+ /** The name of the shared 2D frame profile that hosts and the engine agree on. */
8
9
  export declare const SHARED_FRAME_PROFILE_2D = "egret.shared-frame2d/1";
10
+ /** The type of the shared frame profile name. */
9
11
  export type SharedFrameProfile2D = typeof SHARED_FRAME_PROFILE_2D;
12
+ /** How a frame's output alpha is given: premultiplied, or opaque with alpha ignored. */
10
13
  export type SharedOutputAlpha2D = 'premultiplied' | 'opaque';
14
+ /**
15
+ * Where translucent draws mix with what is under them. `linear` mixes light as it is (the engine's default);
16
+ * `srgb` mixes the stored colour codes, as a 2D canvas and Egret 5 do, so a faint white over a dark ground stays
17
+ * faint. The colour of each draw is the same in both; only the mixing differs.
18
+ */
19
+ export type SharedBlendSpace2D = 'linear' | 'srgb';
20
+ /** The size of a frame to capture, the color it is cleared to, and how its alpha is given. */
11
21
  export interface SharedFrameOptions2D {
12
22
  readonly width: number;
13
23
  readonly height: number;
@@ -15,14 +25,19 @@ export interface SharedFrameOptions2D {
15
25
  readonly clearAlpha?: number;
16
26
  readonly outputAlpha?: SharedOutputAlpha2D;
17
27
  }
28
+ /** One image that a frame's commands sample from, with how its pixels are represented. */
18
29
  export interface SharedPage2D {
30
+ /** Present only for the capture-owned opaque white texel used to fill vector paths. */
31
+ readonly builtin?: 'solid-white';
19
32
  readonly source: ImageData2D;
20
33
  readonly sourceRepresentation: 'egret.srgb-straight-rgba8/1';
21
34
  readonly canonicalRepresentation: 'egret.alpha8-capped-srgb-pma8/1';
22
35
  }
36
+ /** A region of a page, by the page's index in the frame. */
23
37
  export interface SharedRegion2D extends TextureViewRegion2D {
24
38
  readonly pageIndex: number;
25
39
  }
40
+ /** What every draw command carries: its order, its material, its matrix, its opacity and its clips. */
26
41
  export interface SharedDrawState2D {
27
42
  readonly ordinal: number;
28
43
  readonly occurrenceId: number;
@@ -31,17 +46,20 @@ export interface SharedDrawState2D {
31
46
  readonly opacity: number;
32
47
  readonly clips: readonly ClipRectangle2D[];
33
48
  }
49
+ /** A draw command that fills a rectangle with one color. */
34
50
  export interface SharedRectangleCommand2D extends SharedDrawState2D {
35
51
  readonly kind: 'rect';
36
52
  readonly rect: Rectangle2D;
37
53
  readonly fillColor: number;
38
54
  readonly fillAlpha: number;
39
55
  }
56
+ /** A draw command that draws a region of a page. */
40
57
  export interface SharedImageCommand2D extends SharedDrawState2D {
41
58
  readonly kind: 'image';
42
59
  readonly rect: Rectangle2D;
43
60
  readonly regionIndex: number;
44
61
  }
62
+ /** A draw command that draws a textured or colored mesh. */
45
63
  export interface SharedMeshCommand2D extends SharedDrawState2D {
46
64
  readonly kind: 'mesh';
47
65
  readonly regionIndex: number;
@@ -59,6 +77,7 @@ export interface SharedEffect2D {
59
77
  readonly matrix: Matrix2D;
60
78
  readonly clips: readonly ClipRectangle2D[];
61
79
  }
80
+ /** A glow or outline drawn around what an effect layer holds. */
62
81
  export interface SharedGlow2D {
63
82
  readonly kind: 'glow' | 'outline';
64
83
  readonly color: number;
@@ -71,6 +90,7 @@ export interface SharedGlow2D {
71
90
  readonly offsetX: number;
72
91
  readonly offsetY: number;
73
92
  }
93
+ /** A command that ends or begins an effect layer: what came before is finished before what comes after is drawn. */
74
94
  export interface SharedBarrierCommand2D {
75
95
  readonly effect?: SharedEffect2D;
76
96
  readonly kind: 'barrier';
@@ -79,13 +99,15 @@ export interface SharedBarrierCommand2D {
79
99
  readonly boundaryId: number;
80
100
  readonly reason: 'explicit-enter' | 'explicit-exit' | 'clip-enter' | 'clip-exit' | 'empty' | 'effect-enter' | 'effect-exit';
81
101
  }
102
+ /** Any command of a shared frame. */
82
103
  export type SharedRenderCommand2D = SharedRectangleCommand2D | SharedImageCommand2D | SharedMeshCommand2D | SharedBarrierCommand2D;
83
104
  declare const sharedRenderFrame2DBrand: unique symbol;
105
+ /** One captured frame: its size, clear color and color recipe, its commands in draw order, and the pages, regions, materials and geometries they use. */
84
106
  export interface SharedRenderFrame2D {
85
107
  readonly [sharedRenderFrame2DBrand]: true;
86
108
  readonly profile: SharedFrameProfile2D;
87
- readonly colorRecipe: 'egret.linear-srgb-pma/1';
88
- readonly targetRepresentation: 'egret.srgb-pma8-target/1';
109
+ readonly colorRecipe: 'egret.linear-srgb-pma/1' | 'egret.srgb-pma/1';
110
+ readonly targetRepresentation: 'egret.srgb-pma8-target/1' | 'egret.encoded-srgb-pma8-target/1';
89
111
  readonly outputRepresentation: 'egret.srgb-premultiplied-unorm8/1' | 'egret.srgb-opaque-unorm8/1';
90
112
  readonly frameId: number;
91
113
  readonly width: number;
@@ -99,8 +121,11 @@ export interface SharedRenderFrame2D {
99
121
  readonly materials: readonly SharedMaterial2D[];
100
122
  readonly geometries: readonly (TexturedGeometry2D | SharedGeometry2D)[];
101
123
  }
124
+ /** A host that draws shared frames of this profile. */
102
125
  export interface SharedRenderHostAdapter extends HostAdapter {
103
126
  readonly sharedFrameProfile: SharedFrameProfile2D;
127
+ /** The blend space the renderer was made for, `linear` when absent. An Engine's frames record it. */
128
+ readonly sharedBlendSpace?: SharedBlendSpace2D;
104
129
  renderSharedFrame(frame: SharedRenderFrame2D): undefined;
105
130
  }
106
131
  export {};
@@ -1,4 +1,5 @@
1
1
  // This erased shape is not frame authority. Only the Engine registers a fully
2
2
  // captured immutable value; no public constructor or symbol can do so.
3
+ /** The name of the shared 2D frame profile that hosts and the engine agree on. */
3
4
  export const SHARED_FRAME_PROFILE_2D = 'egret.shared-frame2d/1';
4
5
  //# sourceMappingURL=SharedRenderFrame2D.js.map
@@ -1,6 +1,9 @@
1
1
  declare const texturedGeometry2DBrand: unique symbol;
2
+ /** A float array of a textured geometry, in single or double precision. */
2
3
  export type TexturedFloatArray2D = Float32Array<ArrayBuffer> | Float64Array<ArrayBuffer>;
4
+ /** An index array of a textured geometry, in 16 or 32 bits. */
3
5
  export type TexturedIndexArray2D = Uint16Array<ArrayBuffer> | Uint32Array<ArrayBuffer>;
6
+ /** The positions, texture coordinates and triangle indices of a textured mesh to copy. */
4
7
  export interface TexturedGeometry2DInput {
5
8
  readonly positions: TexturedFloatArray2D;
6
9
  readonly uvs: TexturedFloatArray2D;
@@ -19,7 +22,9 @@ export interface TexturedGeometry2D {
19
22
  readonly lightColors: readonly number[];
20
23
  readonly indices: readonly number[];
21
24
  }
25
+ /** Copies and checks a textured mesh; malformed arrays are refused with a TypeError. */
22
26
  export declare function createTexturedGeometry2D(input: TexturedGeometry2DInput): TexturedGeometry2D;
27
+ /** Whether a value is a geometry made by `createTexturedGeometry2D`, without reading any of its properties. */
23
28
  export declare function isTexturedGeometry2D(value: unknown): value is TexturedGeometry2D;
24
29
  export {};
25
30
  //# sourceMappingURL=TexturedGeometry2D.d.ts.map
@@ -102,6 +102,7 @@ function canonical(source, length, kind, vertexCount) {
102
102
  }
103
103
  return freeze(result);
104
104
  }
105
+ /** Copies and checks a textured mesh; malformed arrays are refused with a TypeError. */
105
106
  export function createTexturedGeometry2D(input) {
106
107
  if (typeof input !== 'object' || input === null)
107
108
  throw new TypeFault('Textured geometry descriptor must be an object');
@@ -158,6 +159,7 @@ export function createTexturedGeometry2D(input) {
158
159
  apply(weakSet, owned, [geometry, true]);
159
160
  return geometry;
160
161
  }
162
+ /** Whether a value is a geometry made by `createTexturedGeometry2D`, without reading any of its properties. */
161
163
  export function isTexturedGeometry2D(value) {
162
164
  // WeakMap identity performs no property read, even on revoked Proxies.
163
165
  return typeof value === 'object' && value !== null && apply(weakHas, owned, [value]);
package/dist/index.d.ts CHANGED
@@ -14,7 +14,7 @@ export { createSharedGeometry2D, isSharedGeometry2D } from './SharedGeometry2D.j
14
14
  export type { SharedFloatArray2D, SharedIndexArray2D, SharedGeometryInput2D, SharedGeometry2D } from './SharedGeometry2D.js';
15
15
  export type { TextureViewRegionInput2D, TextureViewRegion2D } from './TextureViewRegion2D.js';
16
16
  export { SHARED_FRAME_PROFILE_2D } from './SharedRenderFrame2D.js';
17
- export type { SharedFrameProfile2D, SharedOutputAlpha2D, SharedFrameOptions2D, SharedPage2D, SharedRegion2D, SharedDrawState2D, SharedRectangleCommand2D, SharedImageCommand2D, SharedMeshCommand2D, SharedBarrierCommand2D, SharedRenderCommand2D, SharedRenderFrame2D, SharedRenderHostAdapter } from './SharedRenderFrame2D.js';
17
+ export type { SharedFrameProfile2D, SharedOutputAlpha2D, SharedBlendSpace2D, SharedFrameOptions2D, SharedPage2D, SharedRegion2D, SharedDrawState2D, SharedRectangleCommand2D, SharedImageCommand2D, SharedMeshCommand2D, SharedBarrierCommand2D, SharedRenderCommand2D, SharedRenderFrame2D, SharedRenderHostAdapter } from './SharedRenderFrame2D.js';
18
18
  export type { ProjectId, EntityId, FileId, TransactionId, ProjectRevision, Sha256, JsonValue, JsonObject, ProjectVersionPins, ProjectReference, ProjectEntity, ProjectFileRole, ProjectFile, ProjectSnapshot, ProjectTransactionSource, ProjectTransactionScope, ProjectOperation, ProjectEditTransaction, ProjectRestoreTransaction, ProjectTransaction, ProjectHistory } from './ProjectFormat.generated.js';
19
19
  export type { SharedEffect2D, SharedGlow2D } from './SharedRenderFrame2D.js';
20
20
  //# sourceMappingURL=index.d.ts.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@egret/contracts",
3
- "version": "7.0.1-rc.3",
3
+ "version": "7.0.2",
4
4
  "type": "module",
5
5
  "exports": {
6
6
  ".": {