impr: Depreacte the partialWrite API and add patch API that better matches the write features (#2355)

Author: reczkok

apps/typegpu-docs/src/content/docs/fundamentals/buffers.mdx

@@ -364,22 +364,21 @@ buffer.write([d.vec3u(4, 5, 6)], {
 ```
 
 :::note
-In this particular case the `writePartial` method described in the next section would be a more convenient option, but the `startOffset` and `endOffset` options are useful for writing bigger slices of data.
+In this particular case the `patch` method described in the next section would be a more convenient option, but the `startOffset` and `endOffset` options are useful for writing bigger slices of data.
 :::
 
-### Partial writes
+### Patching buffers
 
-When you want to update only a subset of a buffer’s fields, you can use the `.writePartial(data)` method. This method updates only the fields provided in the `data` object and leaves the rest unchanged.
+When you want to update only a subset of a buffer’s fields, you can use the `.patch(data)` method. This method updates only the fields provided in the `data` object and leaves the rest unchanged.
 
 The format of the `data` value depends on your schema type:
 
 - **For `d.struct` schemas:**
   Provide an object with keys corresponding to the subset of the schema’s fields you wish to update.
 
 - **For `d.array` schemas:**
-  Provide an array of objects. Each object should specify:
-  - `idx`: the index of the element to update.
-  - `value`: the new value for that element.
+  Provide an object with numeric keys as indices mapped to new values (sparse update),
+  a plain array for full replacement, or a `TypedArray` for byte-level replacement.
 
 ```ts twoslash
 import tgpu, { d } from 'typegpu';
@@ -394,12 +393,12 @@ const Planet = d.struct({
 
 const planetBuffer = root.createBuffer(Planet);
 
-planetBuffer.writePartial({
+planetBuffer.patch({
   mass: 123.1,
-  colors: [
-    { idx: 2, value: d.vec3f(1, 0, 0) },
-    { idx: 4, value: d.vec3f(0, 0, 1) },
-  ],
+  colors: {
+    2: d.vec3f(1, 0, 0),
+    4: d.vec3f(0, 0, 1),
+  },
 });
 ```
 

apps/typegpu-docs/src/content/docs/integration/wesl-interoperability.mdx

@@ -124,15 +124,12 @@ const buffer = root.createBuffer(FishArray(512)).$usage('storage');
 //    ^?
 
 // Updating the 123rd fish's position
-buffer.writePartial([
-  {
-    idx: 123,
-    value: {
-      state: {
-        posit
-        //   ^|
-      },
-    }
+buffer.patch({
+  123: {
+    state: {
+      posit
+      //   ^|
+    },
   }
-]);
+});
 ```

apps/typegpu-docs/src/examples/algorithms/genetic-racing/index.ts

@@ -401,7 +401,7 @@ function updateAspect() {
     return;
   }
   lastAspect = nextAspect;
-  params.writePartial({ aspect: nextAspect });
+  params.patch({ aspect: nextAspect });
 }
 
 function updatePopulation(nextPopulation: number) {
@@ -410,7 +410,7 @@ function updatePopulation(nextPopulation: number) {
     return;
   }
   population = clamped;
-  params.writePartial({ population: clamped });
+  params.patch({ population: clamped });
   ga.reinitCurrent(population);
 }
 
@@ -421,7 +421,7 @@ function frame() {
     if (pendingEvolve) {
       ga.evolve(population);
       steps = 0;
-      params.writePartial({ generation: ga.generation });
+      params.patch({ generation: ga.generation });
       pendingEvolve = false;
     }
 
@@ -430,7 +430,7 @@ function frame() {
       pendingEvolve = true;
     } else {
       const innerSteps = Math.min(stepsToRun, STEPS_PER_DISPATCH);
-      params.writePartial({ stepsPerDispatch: innerSteps });
+      params.patch({ stepsPerDispatch: innerSteps });
       const dispatchCount = Math.ceil(stepsToRun / innerSteps);
 
       const simEncoder = root.device.createCommandEncoder();
@@ -480,7 +480,7 @@ function applyTrack(result: TrackResult) {
   trackTexture.write(
     new ImageData(new Uint8ClampedArray(result.data), result.width, result.height),
   );
-  params.writePartial({
+  params.patch({
     spawnX: result.spawn.position[0],
     spawnY: result.spawn.position[1],
     spawnAngle: result.spawn.angle,
@@ -490,7 +490,7 @@ function applyTrack(result: TrackResult) {
 
 function applyGridSize(W: number, H: number) {
   const scale = 5 / Math.max(W, H);
-  params.writePartial(
+  params.patch(
     Object.fromEntries(
       Object.entries(BASE_SPATIAL_PARAMS).map(([k, v]) => [k, v * scale]),
     ) as typeof BASE_SPATIAL_PARAMS,
@@ -511,7 +511,7 @@ function startSimulation() {
   steps = 0;
   pendingEvolve = false;
   displayedBestFitness = 0;
-  params.writePartial({ generation: 0 });
+  params.patch({ generation: 0 });
   ga.init();
 
   updateAspect();
@@ -589,7 +589,7 @@ export const controls = defineControls({
     max: 0.4,
     step: 0.005,
     onSliderChange: (value: number) => {
-      params.writePartial({ mutationRate: value });
+      params.patch({ mutationRate: value });
     },
   },
   'Mutation strength': {
@@ -598,7 +598,7 @@ export const controls = defineControls({
     max: 0.8,
     step: 0.01,
     onSliderChange: (value: number) => {
-      params.writePartial({ mutationStrength: value });
+      params.patch({ mutationStrength: value });
     },
   },
 });

apps/typegpu-docs/src/examples/algorithms/jump-flood-distance/index.ts

@@ -300,7 +300,7 @@ function runFlood() {
 
 function drawAtPosition(canvasX: number, canvasY: number) {
   const rect = canvas.getBoundingClientRect();
-  brushUniform.writePartial({
+  brushUniform.patch({
     center: d.vec2f((canvasX * width) / rect.width, (canvasY * height) / rect.height),
   });
   drawSeed.with(resources.maskBindGroup).dispatchThreads(width, height);
@@ -371,7 +371,7 @@ const onMouseDown = (e: MouseEvent) => {
   if (e.button !== 0 && e.button !== 2) {
     return;
   }
-  brushUniform.writePartial({ erasing: e.button === 2 ? 1 : 0 });
+  brushUniform.patch({ erasing: e.button === 2 ? 1 : 0 });
   isDrawing = true;
   lastDrawPos = null;
   const rect = canvas.getBoundingClientRect();
@@ -395,7 +395,7 @@ const onTouchStart = (e: TouchEvent) => {
   isDrawing = true;
   lastDrawPos = null;
   const rect = canvas.getBoundingClientRect();
-  brushUniform.writePartial({ erasing: e.touches.length === 2 ? 1 : 0 });
+  brushUniform.patch({ erasing: e.touches.length === 2 ? 1 : 0 });
   const pos = getTouchPosition(rect, e.touches);
   interpolateAndDraw(pos.x, pos.y);
 };
@@ -405,7 +405,7 @@ const onTouchMove = (e: TouchEvent) => {
     return;
   }
   e.preventDefault();
-  brushUniform.writePartial({ erasing: e.touches.length === 2 ? 1 : 0 });
+  brushUniform.patch({ erasing: e.touches.length === 2 ? 1 : 0 });
   const rect = canvas.getBoundingClientRect();
   const pos = getTouchPosition(rect, e.touches);
   interpolateAndDraw(pos.x, pos.y);
@@ -427,7 +427,7 @@ canvas.addEventListener('touchend', onTouchEnd);
 canvas.addEventListener('touchcancel', onTouchEnd);
 
 function updateBrushSize() {
-  brushUniform.writePartial({
+  brushUniform.patch({
     radius: Math.ceil(Math.min(width, height) * brushSize),
   });
 }
@@ -449,14 +449,14 @@ export const controls = defineControls({
   'Show positive distance': {
     initial: true,
     onToggleChange(value: boolean) {
-      paramsUniform.writePartial({ showOutside: value ? 1 : 0 });
+      paramsUniform.patch({ showOutside: value ? 1 : 0 });
       render();
     },
   },
   'Show negative distance': {
     initial: false,
     onToggleChange(value: boolean) {
-      paramsUniform.writePartial({ showInside: value ? 1 : 0 });
+      paramsUniform.patch({ showInside: value ? 1 : 0 });
       render();
     },
   },

apps/typegpu-docs/src/examples/geometry/lines-combinations/index.ts

@@ -338,7 +338,7 @@ let subdiv = {
 };
 
 const draw = (timeMs: number) => {
-  uniformsBuffer.writePartial({
+  uniformsBuffer.patch({
     time: timeMs * 1e-3,
   });
   const colorAttachment: ColorAttachment = {
@@ -453,7 +453,7 @@ export const controls = defineControls({
     options: Object.keys(fillOptions),
     onSelectChange: async (selected) => {
       fillType = fillOptions[selected as keyof typeof fillOptions];
-      uniformsBuffer.writePartial({ fillType });
+      uniformsBuffer.patch({ fillType });
     },
   },
   'Subdiv. Level': {

apps/typegpu-docs/src/examples/image-processing/background-segmentation/index.ts

@@ -198,7 +198,7 @@ function updateCropBounds(aspectRatio: number) {
       uvMaxY = uvMinY + cropHeight;
     }
   }
-  paramsUniform.writePartial({
+  paramsUniform.patch({
     cropBounds: d.vec4f(uvMinX, uvMinY, uvMaxX, uvMaxY),
   });
 }
@@ -313,7 +313,7 @@ export const controls = defineControls({
     options: ['mipmaps', 'gaussian'],
     async onSelectChange(value) {
       useGaussianBlur = value === 'gaussian';
-      paramsUniform.writePartial({ useGaussian: useGaussianBlur ? 1 : 0 });
+      paramsUniform.patch({ useGaussian: useGaussianBlur ? 1 : 0 });
     },
   },
   'blur strength': {
@@ -323,7 +323,7 @@ export const controls = defineControls({
     step: 1,
     onSliderChange(newValue) {
       blurStrength = newValue;
-      paramsUniform.writePartial({ sampleBias: blurStrength });
+      paramsUniform.patch({ sampleBias: blurStrength });
     },
   },
   'square crop': {

apps/typegpu-docs/src/examples/image-processing/image-tuning/index.ts

@@ -284,7 +284,7 @@ export const controls = defineControls({
     onSelectChange: async (selected) => {
       if (selected === 'None') {
         currentLUTTexture = defaultLUTTexture;
-        lut.writePartial({ enabled: 0 });
+        lut.patch({ enabled: 0 });
       } else {
         await updateLUT(LUTFiles[selected as keyof typeof LUTFiles]);
       }
@@ -297,7 +297,7 @@ export const controls = defineControls({
     max: 2.0,
     step: 0.1,
     onSliderChange(value) {
-      adjustments.writePartial({ exposure: value });
+      adjustments.patch({ exposure: value });
       render();
     },
   },
@@ -307,7 +307,7 @@ export const controls = defineControls({
     max: 2.0,
     step: 0.1,
     onSliderChange(value) {
-      adjustments.writePartial({ contrast: value });
+      adjustments.patch({ contrast: value });
       render();
     },
   },
@@ -317,7 +317,7 @@ export const controls = defineControls({
     max: 2.0,
     step: 0.1,
     onSliderChange(value) {
-      adjustments.writePartial({ highlights: value });
+      adjustments.patch({ highlights: value });
       render();
     },
   },
@@ -327,7 +327,7 @@ export const controls = defineControls({
     max: 1.9,
     step: 0.1,
     onSliderChange(value) {
-      adjustments.writePartial({ shadows: value });
+      adjustments.patch({ shadows: value });
       render();
     },
   },
@@ -337,7 +337,7 @@ export const controls = defineControls({
     max: 2.0,
     step: 0.1,
     onSliderChange(value) {
-      adjustments.writePartial({ saturation: value });
+      adjustments.patch({ saturation: value });
       render();
     },
   },

apps/typegpu-docs/src/examples/rendering/box-raytracing/index.ts

@@ -262,7 +262,7 @@ const runner = (timestamp: number) => {
     Math.sin(frame) * cameraDistance + cameraAnchor.z,
   );
 
-  uniforms.writePartial({
+  uniforms.patch({
     canvasDims: d.vec2f(width, height),
     invViewMatrix: mat4.aim(cameraPosition, cameraAnchor, d.vec3f(0, 1, 0), d.mat4x4f()),
   });
@@ -300,7 +300,7 @@ export const controls = defineControls({
     min: 0.1,
     max: 1,
     onSliderChange: (value) => {
-      uniforms.writePartial({
+      uniforms.patch({
         boxSize: value,
       });
     },
@@ -311,7 +311,7 @@ export const controls = defineControls({
     min: 0.2,
     max: 2,
     onSliderChange: (value) => {
-      uniforms.writePartial({
+      uniforms.patch({
         materialDensity: value,
       });
     },

apps/typegpu-docs/src/examples/rendering/clouds/index.ts

@@ -94,7 +94,7 @@ resizeObserver.observe(canvas);
 let frameId: number;
 
 function render(timestamp: number) {
-  paramsUniform.writePartial({ time: (timestamp / 1000) % 500 });
+  paramsUniform.patch({ time: (timestamp / 1000) % 500 });
 
   pipeline
     .with(bindGroup)
@@ -137,7 +137,7 @@ export const controls = defineControls({
     initial: 'medium',
     options: ['very high', 'high', 'medium', 'low', 'very low'],
     onSelectChange(value) {
-      paramsUniform.writePartial(qualityOptions[value]);
+      paramsUniform.patch(qualityOptions[value]);
     },
   },
 });