# InspectMaterial

Shape returned by inspect materials such as `wireframeMaterial` and `normalDebugMaterial`. It bundles the configured pipeline, group-0 layout, uniform size, and a helper to encode shared matrices into a uniform buffer.

## Import

```ts
import type { InspectMaterial } from "@vgpu/render/inspect";
```

## Signature

```ts
import type { InspectMaterialUniformParams } from "@vgpu/render/inspect";

export interface InspectMaterial {
  readonly pipeline: GPURenderPipeline;
  readonly bindGroupLayout: GPUBindGroupLayout;
  readonly uniformByteSize: number;
  readonly writeUniforms: (
    buffer: GPUBuffer,
    offset: number,
    params: InspectMaterialUniformParams,
  ) => void;
}
```

## Fields

| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
| pipeline | `GPURenderPipeline` | ✔ | — | Ready-to-use pipeline configured for the corresponding inspector material. |
| bindGroupLayout | `GPUBindGroupLayout` | ✔ | — | Group 0 layout with binding 0 as a uniform buffer. Allocate a buffer with at least `uniformByteSize` bytes and bind it with this layout. |
| uniformByteSize | `number` | ✔ | — | Exact byte size that `writeUniforms` writes. `normalDebugMaterial()` returns `128`; `wireframeMaterial()` returns `144` because it appends RGB color data. |
| writeUniforms | `(buffer: GPUBuffer, offset: number, params: InspectMaterialUniformParams) => void` | ✔ | — | Packs `viewProjectionMatrix` at float offset 0 and `modelMatrix` at float offset 16, then writes bytes with `device.gpu.queue.writeBuffer(...)`. Wireframe materials also write color at float offset 32. |

**Returns:** Not applicable for the interface itself. Inspector factory functions return frozen `InspectMaterial` objects whose fields can be reused across frames.

**Throws:** None from reading the fields. `writeUniforms(...)` itself performs no custom validation; native WebGPU validation can occur if `buffer` is destroyed, too small for `offset + uniformByteSize`, or missing `GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST` compatibility for the caller's bind group/update path.

## Examples

```ts
import { createMockAdapter } from "@vgpu/adapter-mock";
import { normalDebugMaterial } from "@vgpu/render/inspect";

const device = await createMockAdapter().requestDevice();
const material = normalDebugMaterial({ device, targetFormat: "rgba8unorm-srgb" });
const uniformBuffer = device.createBuffer({
  label: "inspect.normal.uniforms",
  size: material.uniformByteSize,
  usage: ["uniform", "copy_dst"],
});

const identity = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
material.writeUniforms(uniformBuffer.gpu, 0, {
  viewProjectionMatrix: identity,
  modelMatrix: identity,
});

uniformBuffer.destroy();
device.destroy();
```

```ts
import { createMockAdapter } from "@vgpu/adapter-mock";
import { wireframeMaterial } from "@vgpu/render/inspect";

const device = await createMockAdapter().requestDevice();
const material = wireframeMaterial({
  device,
  color: [0.25, 0.5, 1],
  targetFormat: "rgba8unorm-srgb",
});

const uniformBuffer = device.createBuffer({ size: material.uniformByteSize, usage: ["uniform", "copy_dst"] });
const identity = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
material.writeUniforms(uniformBuffer.gpu, 0, { viewProjectionMatrix: identity, modelMatrix: identity });

uniformBuffer.destroy();
device.destroy();
```

## Notes

- `writeUniforms` writes the shared camera view-projection and per-mesh model matrices, so every inspect material can share the same uniform allocation logic.
- Reuse one uniform buffer per material instance; pass offsets when interleaving data for multiple meshes.
- `InspectMaterial` is a shared return contract; material-specific defaults live on the factory docs (`wireframeMaterial`, `normalDebugMaterial`).
- **See also:** `InspectMaterialUniformParams`, `wireframeMaterial`, `normalDebugMaterial`

---

# InspectMaterialUniformParams

Uniform inputs shared by all inspect materials. Additional inspector-specific uniforms should extend this interface explicitly.

## Import

```ts
import type { InspectMaterialUniformParams } from "@vgpu/render/inspect";
```

## Signature

```ts
type Mat4 = Float32Array;

export interface InspectMaterialUniformParams {
  readonly viewProjectionMatrix: Mat4;
  readonly modelMatrix: Mat4;
}
```

## Fields

| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
| viewProjectionMatrix | `Mat4` | ✔ | — | Combined camera matrix written to the inspector's uniform buffer slots 0–63 bytes. |
| modelMatrix | `Mat4` | ✔ | — | Object transform written immediately after `viewProjectionMatrix`, in slots 64–127 bytes. |

**Returns:** Not applicable. This is a parameter object passed to `InspectMaterial.writeUniforms(...)`.

**Throws:** None by itself. The receiving `writeUniforms(...)` call can surface native WebGPU validation if the destination buffer is invalid.

## Examples

```ts
import type { InspectMaterialUniformParams } from "@vgpu/render/inspect";

const identity = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
const params: InspectMaterialUniformParams = {
  viewProjectionMatrix: identity,
  modelMatrix: identity,
};

params.modelMatrix satisfies Float32Array;
```

## Notes

- The interface is intentionally minimal so different inspectors can share the same math; extend it when a tool needs more uniforms.
- Matrices are expected to be column-major `Float32Array` values matching the mesh layout used elsewhere in vgpu.
- **See also:** `InspectMaterial`, `wireframeMaterial`, `normalDebugMaterial`