├── CODEOWNERS ├── .npmignore ├── .gitignore ├── CONTRIBUTORS ├── vite.config.js ├── .github └── workflow ├── buffer-backed-object.type-test.ts ├── package.json ├── CONTRIBUTING ├── README.md ├── LICENSE ├── buffer-backed-object.ts └── buffer-backed-object.test.js /CODEOWNERS: -------------------------------------------------------------------------------- 1 | * @surma 2 | -------------------------------------------------------------------------------- /.npmignore: -------------------------------------------------------------------------------- 1 | coverage 2 | node_modules -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | coverage 2 | dist 3 | node_modules 4 | -------------------------------------------------------------------------------- /CONTRIBUTORS: -------------------------------------------------------------------------------- 1 | # People who have agreed to one of the CLAs and can contribute patches. 2 | # The AUTHORS file lists the copyright holders; this file 3 | # lists people. For example, Google employees are listed here 4 | # but not in AUTHORS, because Google holds the copyright. 5 | # 6 | # https://developers.google.com/open-source/cla/individual 7 | # https://developers.google.com/open-source/cla/corporate 8 | # 9 | # Names should be added to this file as: 10 | # Name 11 | Surma 12 | -------------------------------------------------------------------------------- /vite.config.js: -------------------------------------------------------------------------------- 1 | import { defineConfig } from "vite"; 2 | 3 | export default defineConfig({ 4 | build: { 5 | lib: { 6 | entry: "./buffer-backed-object.ts", 7 | formats: ["es", "cjs", "umd"], 8 | name: "buffer-backed-object", 9 | fileName: (format, entryName) => { 10 | if (format == "es") return `${entryName}.js`; 11 | if (format == "cjs") return `${entryName}.cjs`; 12 | if (format == "umd") return `${entryName}.umd.js`; 13 | }, 14 | }, 15 | }, 16 | }); 17 | -------------------------------------------------------------------------------- /.github/workflow: -------------------------------------------------------------------------------- 1 | name: Node.js CI 2 | 3 | on: 4 | push: 5 | branches: [ main ] 6 | pull_request: 7 | branches: [ main ] 8 | 9 | jobs: 10 | build: 11 | 12 | runs-on: ubuntu-latest 13 | 14 | strategy: 15 | matrix: 16 | node-version: [18.x] 17 | 18 | steps: 19 | - uses: actions/checkout@v3 20 | - name: Use Node.js ${{ matrix.node-version }} 21 | uses: actions/setup-node@v3 22 | with: 23 | node-version: ${{ matrix.node-version }} 24 | - run: npm ci 25 | - run: npm run build 26 | - run: npm test -------------------------------------------------------------------------------- /buffer-backed-object.type-test.ts: -------------------------------------------------------------------------------- 1 | import { assert, IsExact } from "conditional-type-checks"; 2 | 3 | import * as BBO from "./buffer-backed-object.js"; 4 | 5 | const view = BBO.BufferBackedObject(null as any, { 6 | id: BBO.Uint16({ endianness: "little" }), 7 | name: BBO.UTF8String(32), 8 | position: BBO.NestedBufferBackedObject({ 9 | x: BBO.Float64(), 10 | y: BBO.Float64(), 11 | z: BBO.Float64(), 12 | }), 13 | }); 14 | 15 | assert>(true); 16 | assert>(true); 17 | assert>(true); 18 | 19 | const descriptors = { 20 | id: BBO.Uint16({ endianness: "little" }), 21 | name: BBO.UTF8String(32), 22 | }; 23 | const view2 = BBO.ArrayOfBufferBackedObjects(null as any, descriptors); 24 | 25 | assert>>(true); 26 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "buffer-backed-object", 3 | "version": "1.0.1", 4 | "description": "", 5 | "repository": "github:GoogleChromeLabs/buffer-backed-object", 6 | "homepage": "https://github.com/GoogleChromeLabs/buffer-backed-object#readme", 7 | "source": "buffer-backed-object.js", 8 | "module": "dist/buffer-backed-object.modern.js", 9 | "main": "dist/buffer-backed-object.umd.js", 10 | "types": "dist/buffer-backed-object.d.ts", 11 | "scripts": { 12 | "build": "mkdir -p dist && run-s build:bundle build:types", 13 | "build:bundle": "vite build", 14 | "build:types": "tsc --emitDeclarationOnly -d --outFile dist/buffer-backed-object.d.ts buffer-backed-object.ts", 15 | "test": "run-p test:*", 16 | "test:unit": "vitest run --coverage", 17 | "test:types": "tsc --noEmit buffer-backed-object.type-test.ts" 18 | }, 19 | "author": "Surma ", 20 | "license": "Apache-2.0", 21 | "devDependencies": { 22 | "@vitest/coverage-c8": "^0.26.3", 23 | "conditional-type-checks": "^1.0.6", 24 | "npm-run-all": "^4.1.5", 25 | "typescript": "^4.9.4", 26 | "vite": "^4.0.4", 27 | "vitest": "^0.26.3" 28 | } 29 | } 30 | -------------------------------------------------------------------------------- /CONTRIBUTING: -------------------------------------------------------------------------------- 1 | Want to contribute? Great! First, read this page (including the small print at the end). 2 | 3 | ### Before you contribute 4 | Before we can use your code, you must sign the 5 | [Google Individual Contributor License Agreement] 6 | (https://cla.developers.google.com/about/google-individual) 7 | (CLA), which you can do online. The CLA is necessary mainly because you own the 8 | copyright to your changes, even after your contribution becomes part of our 9 | codebase, so we need your permission to use and distribute your code. We also 10 | need to be sure of various other things—for instance that you'll tell us if you 11 | know that your code infringes on other people's patents. You don't have to sign 12 | the CLA until after you've submitted your code for review and a member has 13 | approved it, but you must do it before we can put your code into our codebase. 14 | Before you start working on a larger contribution, you should get in touch with 15 | us first through the issue tracker with your idea so that we can help out and 16 | possibly guide you. Coordinating up front makes it much easier to avoid 17 | frustration later on. 18 | 19 | ### Code reviews 20 | All submissions, including submissions by project members, require review. We 21 | use Github pull requests for this purpose. 22 | 23 | ### The small print 24 | Contributions made by corporations are covered by a different agreement than 25 | the one above, the 26 | [Software Grant and Corporate Contributor License Agreement] 27 | (https://cla.developers.google.com/about/google-corporate). 28 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # `BufferBackedObject` 2 | 3 | **`BufferBackedObject` creates objects that are backed by an `ArrayBuffer`**. It takes a schema definition and de/serializes data on-demand using [`DataView`][dataview] under the hood. The goal is to make [`ArrayBuffer`][arraybuffer]s more convenient to use. 4 | 5 | ``` 6 | npm i -S buffer-backed-object 7 | ``` 8 | 9 | ## Why? 10 | 11 | ### Web Workers 12 | 13 | When using [Web Workers], the performance of `postMessage()` (or the [structured clone algorithm][structured clone] to be exact) is often a concern. While [`postMessage()` is a lot faster than most people give it credit for][is postmessage slow], it can still occasionally be a bottle-neck, especially with bigger payloads. [`ArrayBuffer`][arraybuffer] and their [views][arraybufferview] are incredibly quick to clone (or can even be [transferred][transferable]), but getting data in and out of `ArrayBuffer`s can be cumbersome. `BufferBackedObject` makes this easy by giving you a (seemingly) normal JavaScript object that reads and write values from the `ArrayBuffer` on demand. This means that the serialization & deserialization costs are deferred to the point of access rather than paid upfront, as it is the case with `postMessage()`. 14 | 15 | ### WebGL 16 | 17 | [WebGL Buffers][webgl buffer] can store multiple attributes per vertex using [`vertexAttribPointer()`][vertexattribpointer]. These attributes can be a 3D position, but also other additional data like a normal vector, a color or a texture ID. The underlying buffer contains all the attributes for all the vertices in an interleaved format, which can make manipulating that data quite hard. With `ArrayOfBufferBackedObjects` you can manipulate each vertex individually. Additionally, `ArrayOfBufferBackedObjects` is populated lazily (see more below), allowing you to handle big arrays of vertices more efficiently. 18 | 19 | ### WebGPU 20 | 21 | Similary, you can define structs in WGLS and read from/write to GPU memory buffers. With `BufferBackedObject` or `ArrayOfBufferBackedObjects`, you can manipulate those structs from JavaScript more easily and efficiently. 22 | 23 | ## Example 24 | 25 | ```js 26 | import * as BBO from "buffer-backed-object"; 27 | 28 | const buffer = new ArrayBuffer(100); 29 | const view = BBO.BufferBackedObject(buffer, { 30 | id: BBO.Uint16({ endianness: "big" }), 31 | position: BBO.NestedBufferBackedObject({ 32 | x: BBO.Float32(), 33 | y: BBO.Float32(), 34 | z: BBO.Float32(), 35 | }), 36 | normal: BBO.NestedBufferBackedObject({ 37 | x: BBO.Float32(), 38 | y: BBO.Float32(), 39 | z: BBO.Float32(), 40 | }), 41 | textureId: BBO.Uint8(), 42 | }); 43 | 44 | view.id = 3; 45 | console.log(new Uint8Array(buffer)); 46 | // logs: Uint8Array(100) [3, 0, ...] 47 | console.log(JSON.stringify(view)); 48 | // logs: {"id": 3, "position": {"x": 0, ...}, ...} 49 | ``` 50 | 51 | `ArrayOfBufferBackedObjects` interprets the given `ArrayBuffer` as an _array_ of objects with the given schema: 52 | 53 | ```js 54 | import * as BBO from "buffer-backed-object"; 55 | 56 | const buffer = new ArrayBuffer(100); 57 | const view = BBO.ArrayOfBufferBackedObjects(buffer, { 58 | id: BBO.Uint16({ endianness: "big" }), 59 | position: BBO.NestedBufferBackedObject({ 60 | x: BBO.Float32(), 61 | y: BBO.Float32(), 62 | z: BBO.Float32(), 63 | }), 64 | normal: BBO.NestedBufferBackedObject({ 65 | x: BBO.Float32(), 66 | y: BBO.Float32(), 67 | z: BBO.Float32(), 68 | }), 69 | textureId: BBO.Uint8(), 70 | }); 71 | 72 | // The struct takes up a total of 27 bytes, so 73 | // 3 structs can fit into a 100 byte `ArrayBuffer`. 74 | console.log(view.length); 75 | // logs: 3 76 | 77 | view[0].id = 1000; 78 | view[1].id = 1001; 79 | view[2].id = 1002; 80 | console.log(new Uint8Array(buffer)); 81 | // logs: Uint8Array(100) [232, 3, ...] 82 | console.log(JSON.stringify(view)); 83 | // logs: [{"id": 1000, ...}, {"id": 1001}, ...] 84 | ``` 85 | 86 | ## API 87 | 88 | The module has the following exports: 89 | 90 | ### `function BufferBackedObject(buffer, descriptors, {byteOffset = 0})` 91 | 92 | The key/value pairs in the `descriptors` object must be declared in the same order as they are laid out in the buffer. The returned object has getters and setters for each of `descriptors` properties and de/serializes them `buffer`, starting at the given `byteOffset`. 93 | 94 | ### `function ArrayOfBufferBackedObjects(buffer, descriptors, {byteOffset = 0, length = 0})` 95 | 96 | Like `BufferBackedObject`, but returns an _array_ of `BufferBackedObject`s. If `length` is 0, as much of the buffer is used as possible. The array is populated lazily under the hood for performance purposes. That is, the individual `BufferBackedObject`s will only be created when their index is accessed. 97 | 98 | ### `function structSize(descriptors)` 99 | 100 | Returns the number of bytes required to store a value with the schema outlined by `descriptors`. 101 | 102 | ### Descriptors 103 | 104 | The following descriptor types are available as individually exported functions 105 | 106 | - `function reserved(numBytes)`: A number of unused bytes. This field will now show up in the object. 107 | - `function Int8()`: An 8-bit signed integer 108 | - `function Uint8()`: An 8-bit unsigned integer 109 | - `function Int16({align = 2, endianness = 'little'})`: An 16-bit signed integer 110 | - `function Uint16({align = 2, endianness = 'little'})`: An 16-bit unsigned integer 111 | - `function Int32({align = 4, endianness = 'little'})`: An 32-bit signed integer 112 | - `function Uint32({align = 4, endianness = 'little'})`: An 32-bit unsigned integer 113 | - `function BigInt64({align = 8, endianness = 'little'})`: An 64-bit signed [`BigInt`][bigint] 114 | - `function BigUint64({align = 8, endianness = 'little'})`: An 64-bit unsigned [`BigInt`][bigint] 115 | - `function Float32({align = 4, endianness = 'little'})`: An 32-bit IEEE754 float 116 | - `function Float64({align = 8, endianness = 'little'})`: An 64-bit IEEE754 float (“double”) 117 | - `function UTF8String(maxBytes)`: A UTF-8 encoded string with the given maximum number of bytes. Trailing NULL bytes will be trimmed after decoding. 118 | - `function NestedBufferBackedObject(descriptors)`: A nested `BufferBackedObject` with the given descriptors 119 | - `function NestedArrayOfBufferBackedObjects(numItems, descriptors)`: A nested `ArrayOfBufferBackedObjects` of length `numItems` with the given descriptors 120 | 121 | ## Defining your own descriptor types 122 | 123 | All the descriptor functions return an object with the following structure: 124 | 125 | ```js 126 | { 127 | align?: 1, // Required aligment 128 | size: 4, // Size required by the type 129 | get(dataView, byteOffset) { 130 | // Decode the value at byteOffset using 131 | // `dataView` or `dataView.buffer` and 132 | // return it. 133 | }, 134 | set(dataView, byteOffset, value) { 135 | // Store `value` at `byteOffset` using 136 | // `dataView` or `dataView.buffer`. 137 | } 138 | } 139 | ``` 140 | 141 | --- 142 | 143 | License Apache-2.0 144 | 145 | [dataview]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView 146 | [arraybuffer]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer 147 | [web workers]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API 148 | [structured clone]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm 149 | [is postmessage slow]: https://surma.dev/things/is-postmessage-slow/ 150 | [arraybufferview]: https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView 151 | [transferable]: https://developer.mozilla.org/en-US/docs/Web/API/Transferable 152 | [bigint]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt 153 | [webgl buffer]: https://developer.mozilla.org/en-US/docs/Web/API/WebGLBuffer 154 | [vertexattribpointer]: https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/vertexAttribPointer 155 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | 2 | Apache License 3 | Version 2.0, January 2004 4 | http://www.apache.org/licenses/ 5 | 6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 7 | 8 | 1. Definitions. 9 | 10 | "License" shall mean the terms and conditions for use, reproduction, 11 | and distribution as defined by Sections 1 through 9 of this document. 12 | 13 | "Licensor" shall mean the copyright owner or entity authorized by 14 | the copyright owner that is granting the License. 15 | 16 | "Legal Entity" shall mean the union of the acting entity and all 17 | other entities that control, are controlled by, or are under common 18 | control with that entity. For the purposes of this definition, 19 | "control" means (i) the power, direct or indirect, to cause the 20 | direction or management of such entity, whether by contract or 21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 22 | outstanding shares, or (iii) beneficial ownership of such entity. 23 | 24 | "You" (or "Your") shall mean an individual or Legal Entity 25 | exercising permissions granted by this License. 26 | 27 | "Source" form shall mean the preferred form for making modifications, 28 | including but not limited to software source code, documentation 29 | source, and configuration files. 30 | 31 | "Object" form shall mean any form resulting from mechanical 32 | transformation or translation of a Source form, including but 33 | not limited to compiled object code, generated documentation, 34 | and conversions to other media types. 35 | 36 | "Work" shall mean the work of authorship, whether in Source or 37 | Object form, made available under the License, as indicated by a 38 | copyright notice that is included in or attached to the work 39 | (an example is provided in the Appendix below). 40 | 41 | "Derivative Works" shall mean any work, whether in Source or Object 42 | form, that is based on (or derived from) the Work and for which the 43 | editorial revisions, annotations, elaborations, or other modifications 44 | represent, as a whole, an original work of authorship. For the purposes 45 | of this License, Derivative Works shall not include works that remain 46 | separable from, or merely link (or bind by name) to the interfaces of, 47 | the Work and Derivative Works thereof. 48 | 49 | "Contribution" shall mean any work of authorship, including 50 | the original version of the Work and any modifications or additions 51 | to that Work or Derivative Works thereof, that is intentionally 52 | submitted to Licensor for inclusion in the Work by the copyright owner 53 | or by an individual or Legal Entity authorized to submit on behalf of 54 | the copyright owner. For the purposes of this definition, "submitted" 55 | means any form of electronic, verbal, or written communication sent 56 | to the Licensor or its representatives, including but not limited to 57 | communication on electronic mailing lists, source code control systems, 58 | and issue tracking systems that are managed by, or on behalf of, the 59 | Licensor for the purpose of discussing and improving the Work, but 60 | excluding communication that is conspicuously marked or otherwise 61 | designated in writing by the copyright owner as "Not a Contribution." 62 | 63 | "Contributor" shall mean Licensor and any individual or Legal Entity 64 | on behalf of whom a Contribution has been received by Licensor and 65 | subsequently incorporated within the Work. 66 | 67 | 2. Grant of Copyright License. Subject to the terms and conditions of 68 | this License, each Contributor hereby grants to You a perpetual, 69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 70 | copyright license to reproduce, prepare Derivative Works of, 71 | publicly display, publicly perform, sublicense, and distribute the 72 | Work and such Derivative Works in Source or Object form. 73 | 74 | 3. Grant of Patent License. Subject to the terms and conditions of 75 | this License, each Contributor hereby grants to You a perpetual, 76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 77 | (except as stated in this section) patent license to make, have made, 78 | use, offer to sell, sell, import, and otherwise transfer the Work, 79 | where such license applies only to those patent claims licensable 80 | by such Contributor that are necessarily infringed by their 81 | Contribution(s) alone or by combination of their Contribution(s) 82 | with the Work to which such Contribution(s) was submitted. If You 83 | institute patent litigation against any entity (including a 84 | cross-claim or counterclaim in a lawsuit) alleging that the Work 85 | or a Contribution incorporated within the Work constitutes direct 86 | or contributory patent infringement, then any patent licenses 87 | granted to You under this License for that Work shall terminate 88 | as of the date such litigation is filed. 89 | 90 | 4. Redistribution. You may reproduce and distribute copies of the 91 | Work or Derivative Works thereof in any medium, with or without 92 | modifications, and in Source or Object form, provided that You 93 | meet the following conditions: 94 | 95 | (a) You must give any other recipients of the Work or 96 | Derivative Works a copy of this License; and 97 | 98 | (b) You must cause any modified files to carry prominent notices 99 | stating that You changed the files; and 100 | 101 | (c) You must retain, in the Source form of any Derivative Works 102 | that You distribute, all copyright, patent, trademark, and 103 | attribution notices from the Source form of the Work, 104 | excluding those notices that do not pertain to any part of 105 | the Derivative Works; and 106 | 107 | (d) If the Work includes a "NOTICE" text file as part of its 108 | distribution, then any Derivative Works that You distribute must 109 | include a readable copy of the attribution notices contained 110 | within such NOTICE file, excluding those notices that do not 111 | pertain to any part of the Derivative Works, in at least one 112 | of the following places: within a NOTICE text file distributed 113 | as part of the Derivative Works; within the Source form or 114 | documentation, if provided along with the Derivative Works; or, 115 | within a display generated by the Derivative Works, if and 116 | wherever such third-party notices normally appear. The contents 117 | of the NOTICE file are for informational purposes only and 118 | do not modify the License. You may add Your own attribution 119 | notices within Derivative Works that You distribute, alongside 120 | or as an addendum to the NOTICE text from the Work, provided 121 | that such additional attribution notices cannot be construed 122 | as modifying the License. 123 | 124 | You may add Your own copyright statement to Your modifications and 125 | may provide additional or different license terms and conditions 126 | for use, reproduction, or distribution of Your modifications, or 127 | for any such Derivative Works as a whole, provided Your use, 128 | reproduction, and distribution of the Work otherwise complies with 129 | the conditions stated in this License. 130 | 131 | 5. Submission of Contributions. Unless You explicitly state otherwise, 132 | any Contribution intentionally submitted for inclusion in the Work 133 | by You to the Licensor shall be under the terms and conditions of 134 | this License, without any additional terms or conditions. 135 | Notwithstanding the above, nothing herein shall supersede or modify 136 | the terms of any separate license agreement you may have executed 137 | with Licensor regarding such Contributions. 138 | 139 | 6. Trademarks. This License does not grant permission to use the trade 140 | names, trademarks, service marks, or product names of the Licensor, 141 | except as required for reasonable and customary use in describing the 142 | origin of the Work and reproducing the content of the NOTICE file. 143 | 144 | 7. Disclaimer of Warranty. Unless required by applicable law or 145 | agreed to in writing, Licensor provides the Work (and each 146 | Contributor provides its Contributions) on an "AS IS" BASIS, 147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 148 | implied, including, without limitation, any warranties or conditions 149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 150 | PARTICULAR PURPOSE. You are solely responsible for determining the 151 | appropriateness of using or redistributing the Work and assume any 152 | risks associated with Your exercise of permissions under this License. 153 | 154 | 8. Limitation of Liability. In no event and under no legal theory, 155 | whether in tort (including negligence), contract, or otherwise, 156 | unless required by applicable law (such as deliberate and grossly 157 | negligent acts) or agreed to in writing, shall any Contributor be 158 | liable to You for damages, including any direct, indirect, special, 159 | incidental, or consequential damages of any character arising as a 160 | result of this License or out of the use or inability to use the 161 | Work (including but not limited to damages for loss of goodwill, 162 | work stoppage, computer failure or malfunction, or any and all 163 | other commercial damages or losses), even if such Contributor 164 | has been advised of the possibility of such damages. 165 | 166 | 9. Accepting Warranty or Additional Liability. While redistributing 167 | the Work or Derivative Works thereof, You may choose to offer, 168 | and charge a fee for, acceptance of support, warranty, indemnity, 169 | or other liability obligations and/or rights consistent with this 170 | License. However, in accepting such obligations, You may act only 171 | on Your own behalf and on Your sole responsibility, not on behalf 172 | of any other Contributor, and only if You agree to indemnify, 173 | defend, and hold each Contributor harmless for any liability 174 | incurred by, or claims asserted against, such Contributor by reason 175 | of your accepting any such warranty or additional liability. 176 | 177 | END OF TERMS AND CONDITIONS 178 | 179 | APPENDIX: How to apply the Apache License to your work. 180 | 181 | To apply the Apache License to your work, attach the following 182 | boilerplate notice, with the fields enclosed by brackets "[]" 183 | replaced with your own identifying information. (Don't include 184 | the brackets!) The text should be enclosed in the appropriate 185 | comment syntax for the file format. We also recommend that a 186 | file or class name and description of purpose be included on the 187 | same "printed page" as the copyright notice for easier 188 | identification within third-party archives. 189 | 190 | Copyright 2020 Google Inc. 191 | 192 | Licensed under the Apache License, Version 2.0 (the "License"); 193 | you may not use this file except in compliance with the License. 194 | You may obtain a copy of the License at 195 | 196 | http://www.apache.org/licenses/LICENSE-2.0 197 | 198 | Unless required by applicable law or agreed to in writing, software 199 | distributed under the License is distributed on an "AS IS" BASIS, 200 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 201 | See the License for the specific language governing permissions and 202 | limitations under the License. -------------------------------------------------------------------------------- /buffer-backed-object.ts: -------------------------------------------------------------------------------- 1 | export type Descriptor = { 2 | size: number; 3 | align?: number; 4 | get(dataview: DataView, byteOffset: number): T; 5 | set(dataview: DataView, byteOffset: number, value: T): void; 6 | }; 7 | 8 | type ExtendedDescriptor = Descriptor & { offset: number }; 9 | 10 | export type Descriptors> = { 11 | [key: string]: T; 12 | }; 13 | 14 | export type DecodedBuffer = { 15 | [K in keyof E]: ReturnType; 16 | }; 17 | 18 | /** 19 | * Returns `true` if `s` can be successfully coerced to a number. 20 | */ 21 | function isNumber(s: any): s is number { 22 | if (typeof s === "symbol") { 23 | return false; 24 | } 25 | return !isNaN(s); 26 | } 27 | 28 | /** 29 | * Returns the next integer bigger than `current` that has the desirged alignment. 30 | */ 31 | function nextAlign(current: number, align: number): number { 32 | let aligned = current - (current % align); 33 | if (current % align != 0) { 34 | aligned += align; 35 | } 36 | return aligned; 37 | } 38 | 39 | export function structSize(descriptors: Descriptors): number { 40 | let stride = 0; 41 | for (const { align = 1, size } of Object.values(descriptors)) { 42 | stride = nextAlign(stride, align) + size; 43 | } 44 | stride = nextAlign(stride, structAlign(descriptors)); 45 | return stride; 46 | } 47 | 48 | export function structAlign(descriptors: Descriptors): number { 49 | return Math.max(...Object.values(descriptors).map((d) => d.align ?? 1)); 50 | } 51 | 52 | export function ArrayOfBufferBackedObjects( 53 | buffer: ArrayBuffer, 54 | descriptors: T, 55 | { byteOffset = 0, length = 0, align = structAlign(descriptors) } = {} 56 | ): Array> { 57 | const dataView = new DataView(buffer, byteOffset); 58 | let stride = 0; 59 | // Copy the descriptors. 60 | // @ts-ignore We will fix up the missing `offset` below 61 | const extendedDescriptors: Descriptors> = { 62 | ...descriptors, 63 | }; 64 | for (const [name, descriptor] of Object.entries(extendedDescriptors)) { 65 | extendedDescriptors[name] = { 66 | ...descriptor, 67 | offset: nextAlign(stride, descriptor.align ?? 1), 68 | }; 69 | stride = extendedDescriptors[name].offset + descriptor.size; 70 | } 71 | stride = nextAlign(stride, align); 72 | if (!length) { 73 | length = Math.floor((buffer.byteLength - byteOffset) / stride); 74 | } 75 | 76 | return new Proxy(new Array(length), { 77 | has(target, propName) { 78 | // The underlying array is hole-y, but we want to pretend that it is not. 79 | // So we need to return `true` for all indices so that `map` et al. work 80 | // as expected. 81 | if (isNumber(propName)) { 82 | return propName < length; 83 | } 84 | if (propName === "buffer") { 85 | return true; 86 | } 87 | return propName in target; 88 | }, 89 | get(target, propName, proxy) { 90 | if (propName === "buffer") { 91 | return buffer; 92 | } 93 | if (!isNumber(propName)) { 94 | let prop = target[propName]; 95 | if (typeof prop === "function") { 96 | prop = prop.bind(proxy); 97 | } 98 | return prop; 99 | } 100 | const idx = parseInt(propName); 101 | const itemOffset = idx * stride; 102 | // Just like real arrays, we return `undefined` 103 | // outside the boundaries. 104 | if (idx >= target.length) { 105 | return undefined; 106 | } 107 | // If there is a hole at the given index, we need to create a new value 108 | // there that has the correct getter and setter functions. 109 | if (!target[idx]) { 110 | target[idx] = {}; 111 | for (const [name, descriptor] of Object.entries(extendedDescriptors)) { 112 | if (!("get" in descriptor)) { 113 | continue; 114 | } 115 | Object.defineProperty(target[idx], name, { 116 | enumerable: true, 117 | get() { 118 | return descriptor.get(dataView, itemOffset + descriptor.offset); 119 | }, 120 | set(value) { 121 | return descriptor.set( 122 | dataView, 123 | itemOffset + descriptor.offset, 124 | value 125 | ); 126 | }, 127 | }); 128 | } 129 | Object.freeze(target[idx]); 130 | } 131 | return target[idx]; 132 | }, 133 | }); 134 | } 135 | 136 | export function BufferBackedObject( 137 | buffer: ArrayBuffer, 138 | descriptors: T, 139 | { byteOffset = 0, align = 1 } = {} 140 | ): DecodedBuffer { 141 | return ArrayOfBufferBackedObjects(buffer, descriptors, { 142 | byteOffset, 143 | align, 144 | })[0]; 145 | } 146 | 147 | export interface EndiannessOption { 148 | endianness: "little" | "big"; 149 | } 150 | 151 | export interface AlignOption { 152 | align: number; 153 | } 154 | 155 | export function Uint16({ 156 | endianness = "little", 157 | align = 2, 158 | }: Partial = {}): Descriptor { 159 | if (endianness !== "big" && endianness !== "little") { 160 | throw Error("Endianness needs to be either 'big' or 'little'"); 161 | } 162 | const littleEndian = endianness === "little"; 163 | return { 164 | align, 165 | size: Uint16Array.BYTES_PER_ELEMENT, 166 | get: (dataView, byteOffset) => dataView.getUint16(byteOffset, littleEndian), 167 | set: (dataView, byteOffset, value) => 168 | dataView.setUint16(byteOffset, value, littleEndian), 169 | }; 170 | } 171 | 172 | export function Uint32({ 173 | endianness = "little", 174 | align = 4, 175 | }: Partial = {}): Descriptor { 176 | if (endianness !== "big" && endianness !== "little") { 177 | throw Error("Endianness needs to be either 'big' or 'little'"); 178 | } 179 | const littleEndian = endianness === "little"; 180 | return { 181 | align, 182 | size: Uint32Array.BYTES_PER_ELEMENT, 183 | get: (dataView, byteOffset) => dataView.getUint32(byteOffset, littleEndian), 184 | set: (dataView, byteOffset, value) => 185 | dataView.setUint32(byteOffset, value, littleEndian), 186 | }; 187 | } 188 | 189 | export function Int16({ 190 | endianness = "little", 191 | align = 2, 192 | }: Partial = {}): Descriptor { 193 | if (endianness !== "big" && endianness !== "little") { 194 | throw Error("Endianness needs to be either 'big' or 'little'"); 195 | } 196 | const littleEndian = endianness === "little"; 197 | return { 198 | align, 199 | size: Int16Array.BYTES_PER_ELEMENT, 200 | get: (dataView, byteOffset) => dataView.getInt16(byteOffset, littleEndian), 201 | set: (dataView, byteOffset, value) => 202 | dataView.setInt16(byteOffset, value, littleEndian), 203 | }; 204 | } 205 | 206 | export function Int32({ 207 | endianness = "little", 208 | align = 4, 209 | }: Partial = {}): Descriptor { 210 | if (endianness !== "big" && endianness !== "little") { 211 | throw Error("Endianness needs to be either 'big' or 'little'"); 212 | } 213 | const littleEndian = endianness === "little"; 214 | return { 215 | align, 216 | size: Int32Array.BYTES_PER_ELEMENT, 217 | get: (dataView, byteOffset) => dataView.getInt32(byteOffset, littleEndian), 218 | set: (dataView, byteOffset, value) => 219 | dataView.setInt32(byteOffset, value, littleEndian), 220 | }; 221 | } 222 | 223 | export function Float32({ 224 | endianness = "little", 225 | align = 4, 226 | }: Partial = {}): Descriptor { 227 | if (endianness !== "big" && endianness !== "little") { 228 | throw Error("Endianness needs to be either 'big' or 'little'"); 229 | } 230 | const littleEndian = endianness === "little"; 231 | return { 232 | align, 233 | size: Float32Array.BYTES_PER_ELEMENT, 234 | get: (dataView, byteOffset) => 235 | dataView.getFloat32(byteOffset, littleEndian), 236 | set: (dataView, byteOffset, value) => 237 | dataView.setFloat32(byteOffset, value, littleEndian), 238 | }; 239 | } 240 | 241 | export function Float64({ 242 | endianness = "little", 243 | align = 8, 244 | }: Partial = {}): Descriptor { 245 | if (endianness !== "big" && endianness !== "little") { 246 | throw Error("Endianness needs to be either 'big' or 'little'"); 247 | } 248 | const littleEndian = endianness === "little"; 249 | return { 250 | align, 251 | size: Float64Array.BYTES_PER_ELEMENT, 252 | get: (dataView, byteOffset) => 253 | dataView.getFloat64(byteOffset, littleEndian), 254 | set: (dataView, byteOffset, value) => 255 | dataView.setFloat64(byteOffset, value, littleEndian), 256 | }; 257 | } 258 | 259 | export function BigInt64({ 260 | endianness = "little", 261 | align = 8, 262 | }: Partial = {}): Descriptor { 263 | if (endianness !== "big" && endianness !== "little") { 264 | throw Error("Endianness needs to be either 'big' or 'little'"); 265 | } 266 | const littleEndian = endianness === "little"; 267 | return { 268 | align, 269 | size: BigInt64Array.BYTES_PER_ELEMENT, 270 | get: (dataView, byteOffset) => 271 | dataView.getBigInt64(byteOffset, littleEndian), 272 | set: (dataView, byteOffset, value) => 273 | dataView.setBigInt64(byteOffset, value, littleEndian), 274 | }; 275 | } 276 | 277 | export function BigUint64({ 278 | endianness = "little", 279 | align = 8, 280 | }: Partial = {}): Descriptor { 281 | if (endianness !== "big" && endianness !== "little") { 282 | throw Error("Endianness needs to be either 'big' or 'little'"); 283 | } 284 | const littleEndian = endianness === "little"; 285 | return { 286 | align, 287 | size: BigUint64Array.BYTES_PER_ELEMENT, 288 | get: (dataView, byteOffset) => 289 | dataView.getBigUint64(byteOffset, littleEndian), 290 | set: (dataView, byteOffset, value) => 291 | dataView.setBigUint64(byteOffset, value, littleEndian), 292 | }; 293 | } 294 | 295 | export function Uint8(): Descriptor { 296 | return { 297 | align: 1, 298 | size: 1, 299 | get: (dataView, byteOffset) => dataView.getUint8(byteOffset), 300 | set: (dataView, byteOffset, value) => dataView.setUint8(byteOffset, value), 301 | }; 302 | } 303 | 304 | export function Int8(): Descriptor { 305 | return { 306 | align: 1, 307 | size: 1, 308 | get: (dataView, byteOffset) => dataView.getInt8(byteOffset), 309 | set: (dataView, byteOffset, value) => dataView.setInt8(byteOffset, value), 310 | }; 311 | } 312 | 313 | export function NestedBufferBackedObject( 314 | descriptors: T 315 | ): Descriptor> { 316 | const size = structSize(descriptors); 317 | return { 318 | align: structAlign(descriptors), 319 | size, 320 | get: (dataView, byteOffset) => 321 | ArrayOfBufferBackedObjects(dataView.buffer, descriptors, { 322 | byteOffset: dataView.byteOffset + byteOffset, 323 | length: 1, 324 | })[0], 325 | set: (dataView, byteOffset, value) => { 326 | throw Error("Can’t set an entire struct"); 327 | }, 328 | }; 329 | } 330 | 331 | export function NestedArrayOfBufferBackedObjects( 332 | length: number, 333 | descriptors: T 334 | ): Descriptor>> { 335 | const size = structSize(descriptors) * length; 336 | return { 337 | align: Object.values(descriptors)[0].align ?? 1, 338 | size, 339 | get: (dataView, byteOffset) => 340 | ArrayOfBufferBackedObjects(dataView.buffer, descriptors, { 341 | byteOffset: byteOffset + dataView.byteOffset, 342 | length, 343 | }), 344 | set: (dataView, byteOffset, value) => { 345 | throw Error("Can’t set an entire array"); 346 | }, 347 | }; 348 | } 349 | 350 | export function UTF8String(maxBytes: number): Descriptor { 351 | return { 352 | align: 1, 353 | size: maxBytes, 354 | get: (dataView, byteOffset) => 355 | new TextDecoder() 356 | .decode(new Uint8Array(dataView.buffer, byteOffset, maxBytes)) 357 | .replace(/\u0000+$/, ""), 358 | set: (dataView, byteOffset, value) => { 359 | const encoding = new TextEncoder().encode(value); 360 | const target = new Uint8Array(dataView.buffer, byteOffset, maxBytes); 361 | target.fill(0); 362 | target.set(encoding.subarray(0, maxBytes)); 363 | }, 364 | }; 365 | } 366 | 367 | export function reserved(size: number): Descriptor { 368 | return { align: 1, size, get() {}, set() {} }; 369 | } 370 | -------------------------------------------------------------------------------- /buffer-backed-object.test.js: -------------------------------------------------------------------------------- 1 | import { expect, test } from "vitest"; 2 | 3 | import * as BBO from "./buffer-backed-object.ts"; 4 | 5 | test("structSize calculates the size of a struct correctly", function () { 6 | { 7 | const size = BBO.structSize({ 8 | id: BBO.Uint8(), 9 | }); 10 | expect(size).toBe(1); 11 | } 12 | 13 | { 14 | const size = BBO.structSize({ 15 | id: BBO.Uint16(), 16 | }); 17 | expect(size).toBe(2); 18 | } 19 | 20 | { 21 | const size = BBO.structSize({ 22 | id: BBO.Uint16(), 23 | id2: BBO.Uint8(), 24 | }); 25 | expect(size).toBe(4); 26 | } 27 | 28 | { 29 | const size = BBO.structSize({ 30 | id: BBO.Uint8(), 31 | id2: BBO.Uint16(), 32 | }); 33 | expect(size).toBe(4); 34 | } 35 | 36 | { 37 | const size = BBO.structSize({ 38 | id: BBO.Uint8(), 39 | id2: BBO.Uint32(), 40 | id3: BBO.Uint32(), 41 | }); 42 | expect(size).toBe(12); 43 | } 44 | 45 | { 46 | const size = BBO.structSize({ 47 | id: BBO.Uint8(), // 0...7 48 | x: BBO.Float64({ endianness: "big" }), // 8...15 49 | y: BBO.Float64({ endianness: "little" }), // 16...23 50 | texture: BBO.Int32(), // 24...28 51 | _: BBO.reserved(1), // 28...29 52 | }); 53 | expect(size).toBe(32); 54 | } 55 | }); 56 | 57 | test("ArrayOfBufferBackedObjects calculates length correctly", function () { 58 | { 59 | const buffer = new ArrayBuffer(7); 60 | const aosv = BBO.ArrayOfBufferBackedObjects(buffer, { 61 | id: BBO.Uint8(), 62 | _: BBO.reserved(1), 63 | }); 64 | expect(aosv.length).toBe(3); 65 | } 66 | 67 | { 68 | const buffer = new ArrayBuffer(47); 69 | const aosv = BBO.ArrayOfBufferBackedObjects(buffer, { 70 | id: BBO.Uint8(), 71 | i2: BBO.BigInt64(), 72 | }); 73 | expect(aosv.length).toBe(2); 74 | } 75 | }); 76 | 77 | test("ArrayOfBufferBackedObjects decodes items correctly", function () { 78 | const descriptor = { 79 | id: BBO.Uint8(), // 0...7 80 | x: BBO.Float64({ endianness: "big" }), // 8...15 81 | y: BBO.Float64({ endianness: "little" }), // 16...23 82 | texture: BBO.Int32(), // 24...27 83 | _: BBO.reserved(1), // 28...29 84 | }; 85 | 86 | console.log(BBO.structSize(descriptor), BBO.structAlign(descriptor)); 87 | const buffer = new ArrayBuffer(BBO.structSize(descriptor) * 2); 88 | const dataView = new DataView(buffer); 89 | dataView.setUint8(0 + 0, 1); 90 | dataView.setUint8(32 + 0, 2); 91 | dataView.setFloat64(0 + 8, 20, false); 92 | dataView.setFloat64(0 + 16, 30, true); 93 | dataView.setFloat64(32 + 8, 40, false); 94 | dataView.setFloat64(32 + 16, 50, true); 95 | dataView.setInt32(0 + 24, 9, true); 96 | dataView.setInt32(32 + 24, 10, true); 97 | const aosv = BBO.ArrayOfBufferBackedObjects(buffer, descriptor); 98 | expect(aosv[0].id).toBe(1); 99 | expect(aosv[1].id).toBe(2); 100 | expect(aosv[0].x).toBe(20); 101 | expect(aosv[1].x).toBe(40); 102 | expect(aosv[0].y).toBe(30); 103 | expect(aosv[1].y).toBe(50); 104 | expect(aosv[0].texture).toBe(9); 105 | expect(aosv[1].texture).toBe(10); 106 | }); 107 | 108 | test("ArrayOfBufferBackedObjects can have an offset", function () { 109 | const descriptor = { 110 | id: BBO.Uint8(), 111 | _: BBO.reserved(1), 112 | }; 113 | const buffer = new ArrayBuffer(BBO.structSize(descriptor) * 4 + 1); 114 | const dataView = new DataView(buffer); 115 | const aosv = BBO.ArrayOfBufferBackedObjects(buffer, descriptor, { 116 | byteOffset: 1, 117 | length: 2, 118 | }); 119 | expect(aosv.length).toBe(2); 120 | aosv[0].id = 1; 121 | aosv[1].id = 1; 122 | expect(dataView.getUint8(1)).toBe(1); 123 | }); 124 | 125 | test("ArrayOfBufferBackedObjects handles nested Array of BBOs", function () { 126 | const descriptors = { 127 | id: BBO.Uint8(), 128 | vertices: BBO.NestedArrayOfBufferBackedObjects(3, { 129 | x: BBO.Float64(), 130 | y: BBO.Float64(), 131 | }), 132 | }; 133 | const buffer = new ArrayBuffer(BBO.structSize(descriptors) * 3); 134 | const aosv = BBO.ArrayOfBufferBackedObjects(buffer, descriptors); 135 | expect(aosv.length).toBe(3); 136 | aosv[2].id = 1; 137 | aosv[2].vertices[0].x = 0; 138 | aosv[2].vertices[0].y = 1; 139 | aosv[2].vertices[1].x = 2; 140 | aosv[2].vertices[1].y = 3; 141 | aosv[2].vertices[2].x = 4; 142 | aosv[2].vertices[2].y = 5; 143 | expect(aosv.length).toBe(3); 144 | expect(JSON.stringify(aosv[2])).toBe( 145 | JSON.stringify({ 146 | id: 1, 147 | vertices: [ 148 | { x: 0, y: 1 }, 149 | { x: 2, y: 3 }, 150 | { x: 4, y: 5 }, 151 | ], 152 | }) 153 | ); 154 | }); 155 | 156 | test("ArrayOfBufferBackedObjects handles nested BBO", function () { 157 | const descriptors = { 158 | id: BBO.Uint8(), 159 | pos: BBO.NestedBufferBackedObject({ 160 | x: BBO.Float64(), 161 | y: BBO.Float64(), 162 | }), 163 | }; 164 | const buffer = new ArrayBuffer(BBO.structSize(descriptors) * 3); 165 | const aosv = BBO.ArrayOfBufferBackedObjects(buffer, descriptors); 166 | expect(aosv.length).toBe(3); 167 | aosv[2].id = 1; 168 | aosv[2].pos.x = 3; 169 | aosv[2].pos.y = 2; 170 | expect(aosv.length).toBe(3); 171 | expect(JSON.stringify(aosv[2])).toBe( 172 | JSON.stringify({ id: 1, pos: { x: 3, y: 2 } }) 173 | ); 174 | expect(JSON.stringify(aosv)).toBe( 175 | JSON.stringify([ 176 | { id: 0, pos: { x: 0, y: 0 } }, 177 | { id: 0, pos: { x: 0, y: 0 } }, 178 | { id: 1, pos: { x: 3, y: 2 } }, 179 | ]) 180 | ); 181 | }); 182 | 183 | test("ArrayOfBufferBackedObjects handles nested BBO with nested arrays", function () { 184 | const PathNodeDescription = { 185 | type: BBO.Uint8(), 186 | x: BBO.Uint32(), 187 | y: BBO.Uint32(), 188 | }; 189 | 190 | const EnemyDescription = { 191 | type: BBO.Uint8(), 192 | x: BBO.Float32(), 193 | y: BBO.Float32(), 194 | path: BBO.NestedArrayOfBufferBackedObjects(1, PathNodeDescription), 195 | }; 196 | 197 | const GameStateDescription = { 198 | gametime: BBO.Uint32(), 199 | season: BBO.Uint8(), 200 | enemies: BBO.NestedArrayOfBufferBackedObjects(1, EnemyDescription), 201 | }; 202 | const gameStateBuffer = new ArrayBuffer(BBO.structSize(GameStateDescription)); 203 | const gameState = BBO.BufferBackedObject( 204 | gameStateBuffer, 205 | GameStateDescription 206 | ); 207 | 208 | gameState.gametime = 12345; 209 | gameState.season = 3; 210 | 211 | expect(gameState.enemies.length).toBe(1); 212 | gameState.enemies[0].type = 1; 213 | gameState.enemies[0].x = 512; 214 | gameState.enemies[0].y = 0; 215 | expect(gameState.enemies.length).toBe(1); 216 | expect(JSON.stringify(gameState.enemies[0])).toBe( 217 | JSON.stringify({ type: 1, x: 512, y: 0, path: [{ type: 0, x: 0, y: 0 }] }) 218 | ); 219 | expect(JSON.stringify(gameState)).toBe( 220 | JSON.stringify({ 221 | gametime: 12345, 222 | season: 3, 223 | enemies: [{ type: 1, x: 512, y: 0, path: [{ type: 0, x: 0, y: 0 }] }], 224 | }) 225 | ); 226 | }); 227 | 228 | test("ArrayOfBufferBackedObjects can return the buffer", function () { 229 | const buffer = new ArrayBuffer(22); 230 | const aosv = BBO.ArrayOfBufferBackedObjects(buffer, { 231 | x: BBO.Uint8(), 232 | }); 233 | expect(aosv.buffer).toBe(buffer); 234 | }); 235 | 236 | test("ArrayOfBufferBackedObjects encodes to JSON", function () { 237 | const { buffer } = new Uint8Array([0, 0, 1, 0, 2, 0, 1]); 238 | const aosv = BBO.ArrayOfBufferBackedObjects(buffer, { 239 | id: BBO.Uint8(), 240 | _: BBO.reserved(1), 241 | }); 242 | expect(JSON.stringify(aosv)).toBe( 243 | JSON.stringify([{ id: 0 }, { id: 1 }, { id: 2 }]) 244 | ); 245 | }); 246 | 247 | test("ArrayOfBufferBackedObjects can write items", function () { 248 | const descriptor = { 249 | id: BBO.Uint8(), 250 | x: BBO.Float64(), 251 | _: BBO.reserved(1), 252 | }; 253 | const buffer = new ArrayBuffer(BBO.structSize(descriptor) * 2); 254 | const dataView = new DataView(buffer); 255 | const aosv = BBO.ArrayOfBufferBackedObjects(buffer, descriptor); 256 | aosv[0].x = 10; 257 | aosv[1].x = 20; 258 | expect(dataView.getFloat64(8, true)).toBe(10); 259 | expect(dataView.getFloat64(32, true)).toBe(20); 260 | }); 261 | 262 | test("ArrayOfBufferBackedObjects handles filter()", function () { 263 | const descriptor = { 264 | id: BBO.Uint8(), 265 | data: BBO.Uint8(), 266 | }; 267 | const { buffer } = new Uint8Array([0, 10, 1, 11, 2, 12, 3, 13]); 268 | const aosv = BBO.ArrayOfBufferBackedObjects(buffer, descriptor); 269 | const even = aosv.filter(({ id }) => id % 2 == 0); 270 | expect(even.length).toBe(2); 271 | even[1].data = 99; 272 | expect(aosv[2].data).toBe(99); 273 | }); 274 | 275 | test("ArrayOfBufferBackedObjects rejects new properties", function () { 276 | const descriptor = { 277 | id: BBO.Uint8(), 278 | data: BBO.Uint8(), 279 | }; 280 | const { buffer } = new Uint8Array([0, 10, 1, 11, 2, 12, 3, 13]); 281 | const aosv = BBO.ArrayOfBufferBackedObjects(buffer, descriptor); 282 | expect(() => { 283 | aosv[0].lol = 4; 284 | }).toThrow(); 285 | }); 286 | 287 | test("ArrayOfBufferBackedObjects can handle UTF8 strings", function () { 288 | const descriptor = { 289 | name: BBO.UTF8String(32), 290 | id: BBO.Uint8(), 291 | }; 292 | const buffer = new ArrayBuffer(BBO.structSize(descriptor) * 2); 293 | const aosv = BBO.ArrayOfBufferBackedObjects(buffer, descriptor); 294 | aosv[0].name = "Surma"; 295 | aosv[1].name = "Jason"; 296 | const name1 = new TextDecoder().decode(new Uint8Array(buffer, 0, 5)); 297 | const name2 = new TextDecoder().decode(new Uint8Array(buffer, 33, 5)); 298 | expect(name1).toBe("Surma"); 299 | expect(name2).toBe("Jason"); 300 | }); 301 | 302 | test("BufferBackedObject decodes items correctly", function () { 303 | const descriptor = { 304 | id: BBO.Uint8(), 305 | x: BBO.Float64({ endianness: "big" }), 306 | y: BBO.Float64({ endianness: "little" }), 307 | texture: BBO.Int32(), 308 | _: BBO.reserved(1), 309 | }; 310 | 311 | const buffer = new ArrayBuffer(BBO.structSize(descriptor)); 312 | const dataView = new DataView(buffer); 313 | dataView.setUint8(0 + 0, 1); 314 | dataView.setFloat64(0 + 8, 20, false); 315 | dataView.setFloat64(0 + 16, 30, true); 316 | dataView.setInt32(0 + 24, 9, true); 317 | const sdv = BBO.BufferBackedObject(buffer, descriptor); 318 | expect(sdv.id).toBe(1); 319 | expect(sdv.x).toBe(20); 320 | expect(sdv.y).toBe(30); 321 | expect(sdv.texture).toBe(9); 322 | }); 323 | 324 | test("BufferBackedObject decodes items correctly with custom align", function () { 325 | const descriptor = { 326 | id: BBO.Uint8(), 327 | x: BBO.Float64({ endianness: "big", align: 1 }), 328 | y: BBO.Float64({ endianness: "little", align: 1 }), 329 | texture: BBO.Int32({ align: 1 }), 330 | _: BBO.reserved(1), 331 | }; 332 | 333 | const buffer = new ArrayBuffer(BBO.structSize(descriptor)); 334 | const dataView = new DataView(buffer); 335 | dataView.setUint8(0 + 0, 1); 336 | dataView.setFloat64(0 + 1, 20, false); 337 | dataView.setFloat64(0 + 9, 30, true); 338 | dataView.setInt32(0 + 17, 9, true); 339 | const sdv = BBO.BufferBackedObject(buffer, descriptor); 340 | expect(sdv.id).toBe(1); 341 | expect(sdv.x).toBe(20); 342 | expect(sdv.y).toBe(30); 343 | expect(sdv.texture).toBe(9); 344 | }); 345 | 346 | test("NestedArrayOfBufferBackedObjects test raw bufferview", function () { 347 | const BBOVec3 = BBO.NestedBufferBackedObject({ 348 | x: BBO.Float32(), 349 | y: BBO.Float32(), 350 | z: BBO.Float32(), 351 | }); 352 | const structDesc = { 353 | ambient: BBOVec3, 354 | lightCount: BBO.Float32(), 355 | lights: BBO.NestedArrayOfBufferBackedObjects(1, { 356 | position: BBOVec3, 357 | range: BBO.Float32(), 358 | color: BBOVec3, 359 | intensity: BBO.Float32(), 360 | }), 361 | }; 362 | const buffer = new ArrayBuffer(BBO.structSize(structDesc)); 363 | const view = BBO.BufferBackedObject(buffer, structDesc); 364 | view.ambient.x = 1; 365 | view.ambient.y = 2; 366 | view.ambient.z = 3; 367 | view.lightCount = 4; 368 | view.lights.forEach(light => { 369 | light.position.x = 5; 370 | light.position.y = 6; 371 | light.position.z = 7; 372 | light.range = 8; 373 | light.color.x = 9; 374 | light.color.y = 10; 375 | light.color.z = 11; 376 | light.intensity = 12; 377 | }); 378 | const f32 = new Float32Array(buffer); 379 | 380 | expect(f32[0]).toBe(1); 381 | expect(f32[1]).toBe(2); 382 | expect(f32[2]).toBe(3); 383 | expect(f32[3]).toBe(4); 384 | expect(f32[4]).toBe(5); 385 | expect(f32[5]).toBe(6); 386 | expect(f32[6]).toBe(7); 387 | expect(f32[7]).toBe(8); 388 | expect(f32[8]).toBe(9); 389 | expect(f32[9]).toBe(10); 390 | expect(f32[10]).toBe(11); 391 | expect(f32[11]).toBe(12); 392 | }); 393 | 394 | test("Nested NestedBufferBackedObjects", function () { 395 | const structDesc = { 396 | somethingElse: BBO.Float32(), 397 | nest1: BBO.NestedBufferBackedObject({ 398 | somethingElse: BBO.Float32(), 399 | nest2: BBO.NestedBufferBackedObject( { 400 | value: BBO.Float32() 401 | }) 402 | }), 403 | }; 404 | const buffer = new ArrayBuffer(BBO.structSize(structDesc)); 405 | const view = BBO.BufferBackedObject(buffer, structDesc); 406 | view.somethingElse = 1; 407 | view.nest1.somethingElse = 2; 408 | view.nest1.nest2.value = 3; 409 | const f32 = new Float32Array(buffer); 410 | 411 | expect(f32[0]).toBe(1); 412 | expect(f32[1]).toBe(2); 413 | expect(f32[2]).toBe(3); 414 | }); 415 | --------------------------------------------------------------------------------