Deploying to gh-pages from @ 581c953 🚀

README.md

@@ -208,6 +208,82 @@ passEncoder.drawIndexed(bi.numElements);
 * [Instancing](examples/instancing.html)
 * [Instancing 2](examples/instancing-size-only.html)
 
+## Notes about structured data
+
+### The first level of an array of intrinsic types is flattened.
+
+Example:
+
+```js
+const code = `
+@group(0) @binding(0) var<uniform> uni1: array<vec3f, 4>;
+@group(0) @binding(1) var<uniform> uni2: array<array<vec3f, 3>, 4>;
+`;
+const defs = makeShaderDataDefinitions(code);
+const uni1 = makeStructuredView(defs.uniforms.uni1);
+const uni2 = makeStructuredView(defs.uniforms.uni2);
+
+uni1.set([
+  1, 2, 3, 0,  // uni1[0]
+  4, 5, 6, 0,  // uni1[1]
+  //...
+]);
+
+uni2.set([
+  [
+    1, 2, 3, 0,  // uni2[0][0],
+    4, 5, 6, 0,  // uni2[0][1],
+  ],
+  ,  // uni2[1]
+  [
+    7, 8, 9, 0,  // uni2[2][0],
+    4, 5, 6, 0,  // uni2[2][1],
+  ],
+]);
+```
+
+The reason it's this way is it's common to make large arrays of `f32`, `u32`,
+`vec2f`, `vec3f`, `vec4f` etc. We couldn't want every element of an array to
+have its own typedarray view.
+
+### arrays of intrinsics can be set by arrays of arrays
+
+```js
+const code = `
+@group(0) @binding(0) var<uniform> uni1: array<vec2f, 4>;
+`;
+const defs = makeShaderDataDefinitions(code);
+const uni1 = makeStructuredView(defs.uniforms.uni1);
+
+uni1.set([
+  [1, 2],  // uni1[0]
+  [3, 4],  // uni1[1]
+]);
+```
+
+Currently this requires the length of each subarray to match the length of
+the intrinsic. The reason being, there is no type data used in `uni1.set` so
+there is nothing to tell it that it's a `vec2f`. In this case, it just advances
+where it's writing by the length of the source data sub arrays.
+
+### for unsized arrays you must pass in your own arrayBuffer
+
+The reason is an unsized array's size is defined to WebGPU by its buffer binding
+size. That information is provided at runtime so there's no way for webgpu-utils
+to know the size. The solution is you pass in an `ArrayBuffer`.
+
+Example:
+
+```js
+const code = `
+@group(0) @binding(0) var<uniform> uni1: array<vec3f>;  // unsized array
+`;
+const defs = makeShaderDataDefinitions(code);
+const uni1 = makeStructuredView(defs.uniforms.uni1, new ArrayBuffer(4 * 16));
+
+// uni.views will be a Float32Array representing 4 vec3fs
+```
+
 ## Usage
 
 * include from the net

dist/0.x/buffer-views.d.ts

@@ -9,7 +9,37 @@ export type ArrayBufferViews = {
     arrayBuffer: ArrayBuffer;
 };
 /**
- * Creates a set of named TypedArray views on an ArrayBuffer
+ * Creates a set of named TypedArray views on an ArrayBuffer. If you don't
+ * pass in an ArrayBuffer, one will be created. If you're using an unsized
+ * array then you must pass in your own arraybuffer
+ *
+ * Example:
+ *
+ * ```js
+ * const code = `
+ * struct Stuff {
+ *    direction: vec3f,
+ *    strength: f32,
+ *    matrix: mat4x4f,
+ * };
+ * @group(0) @binding(0) var<uniform> uni: Stuff;
+ * `;
+ * const defs = makeShaderDataDefinitions(code);
+ * const views = makeTypedArrayViews(devs.uniforms.uni.typeDefinition);
+ * ```
+ *
+ * views would effectively be
+ *
+ * ```js
+ * views = {
+ *   direction: Float32Array(arrayBuffer, 0, 3),
+ *   strength: Float32Array(arrayBuffer, 3, 4),
+ *   matrix: Float32Array(arraybuffer, 4, 20),
+ * };
+ * ```
+ *
+ * You can use the views directly or you can use @link {setStructuredView}
+ *
  * @param typeDef Definition of the various types of views.
  * @param arrayBuffer Optional ArrayBuffer to use (if one provided one will be created)
  * @param offset Optional offset in existing ArrayBuffer to start the views.
@@ -19,6 +49,38 @@ export declare function makeTypedArrayViews(typeDef: TypeDefinition, arrayBuffer
 /**
  * Given a set of TypeArrayViews and matching JavaScript data
  * sets the content of the views.
+ *
+ * Example:
+ *
+ * ```js
+ * const code = `
+ * struct Stuff {
+ *    direction: vec3f,
+ *    strength: f32,
+ *    matrix: mat4x4f,
+ * };
+ * @group(0) @binding(0) var<uniform> uni: Stuff;
+ * `;
+ * const defs = makeShaderDataDefinitions(code);
+ * const views = makeTypedArrayViews(devs.uniforms.uni.typeDefinition);
+ *
+ * setStructuredViews({
+ *   direction: [1, 2, 3],
+ *   strength: 45,
+ *   matrix: [
+ *     1, 0, 0, 0,
+ *     0, 1, 0, 0,
+ *     0, 0, 1, 0,
+ *     0, 0, 0, 1,
+ *   ],
+ * });
+ * ```
+ *
+ * The code above will set the various views, which all point to different
+ * locations within the same array buffer.
+ *
+ * See @link {makeTypedArrayViews}.
+ *
  * @param data The new values
  * @param views TypedArray views as returned from {@link makeTypedArrayViews}
  */
@@ -75,5 +137,19 @@ export type StructuredView = ArrayBufferViews & {
  *    as a `set` function to make them easy to set, and the arrayBuffer
  */
 export declare function makeStructuredView(varDef: VariableDefinition | StructDefinition, arrayBuffer?: ArrayBuffer, offset?: number): StructuredView;
+/**
+ * Sets values on an existing array buffer from a TypeDefinition
+ * @param typeDef A type definition provided by @link {makeShaderDataDefinitions}
+ * @param data The source data
+ * @param arrayBuffer The arrayBuffer who's data to set.
+ * @param offset An offset in the arrayBuffer to start at.
+ */
 export declare function setTypedValues(typeDef: TypeDefinition, data: any, arrayBuffer: ArrayBuffer, offset?: number): void;
+/**
+ * Same as @link {setTypedValues} except it takes a @link {VariableDefinition}.
+ * @param typeDef A variable definition provided by @link {makeShaderDataDefinitions}
+ * @param data The source data
+ * @param arrayBuffer The arrayBuffer who's data to set.
+ * @param offset An offset in the arrayBuffer to start at.
+ */
 export declare function setStructuredValues(varDef: VariableDefinition, data: any, arrayBuffer: ArrayBuffer, offset?: number): void;