# DRP2 Capabilities

This document defines the minimum capability model needed by DRP2.


## Goals

1. Keep the public contract backend-agnostic.
2. Make optional features explicit and testable.
3. Avoid embedding Vulkan-specific or browser-specific constants in the public DRP2 surface.


## Capability Categories

The runtime should expose a structured capability record covering:

1. protocol version support
2. shader language support
3. texture format support
4. sample count support
5. depth/stencil support
6. limits
7. determinism-related guarantees
8. optional native escape hatches outside the core DRP2 contract
9. lower-level rendering features used by scene techniques such as transparency


## Minimum Fields

The first capability schema should include at least:

1. `protocol_version`
2. `max_bind_groups`
3. `max_color_attachments`
4. `max_buffer_size`
5. `max_uniform_buffer_binding_size`
6. `max_storage_buffer_binding_size`
7. `max_texture_dimension_1d`
8. `max_texture_dimension_2d`
9. `max_texture_dimension_3d`
10. `max_texture_array_layers`
11. `supported_texture_formats`
12. `supported_render_target_formats`
13. `supported_sample_counts`
14. `supported_shader_formats`
15. `supports_timestamp_queries`
16. `supports_fp64`
17. `supports_readback`
18. `supports_offscreen_targets`
19. `supports_storage_textures`
20. `supports_color_blending`
21. `min_uniform_buffer_offset_alignment`
22. `min_storage_buffer_offset_alignment`
23. `min_texture_copy_bytes_per_row_alignment`


## Fixture Capability Shape

When a fixture declares `capabilities`, the first active `2.0` capability object should use this
shape:

1. `max_buffer_size`
2. `max_texture_dimension_1d`
3. `max_texture_dimension_2d`
4. `max_texture_dimension_3d`
5. `supported_texture_formats`
6. `supported_sample_counts`
7. `supported_shader_formats`
8. `supports_fp64`

The omitted fields from the broader future capability model remain planned but are not yet consumed
by the first executable fixture corpus.

The fixture capability object is intentionally smaller than the runtime capability snapshot consumed
by the future scene layer. Fixtures should declare only the fields needed to make the fixture's
validation outcome deterministic.


## Runtime Capability Snapshot

A runtime that is consumed by the scene layer should expose a richer `DvzCapabilitySnapshot`.

This runtime snapshot includes the fixture fields above plus scene-planning limits such as:

1. `protocol_version`
2. `max_bind_groups`
3. `max_color_attachments`
4. `max_uniform_buffer_binding_size`
5. `max_storage_buffer_binding_size`
6. `max_texture_array_layers`
7. `supported_render_target_formats`
8. `supports_readback`
9. `supports_offscreen_targets`
10. `supports_storage_textures`
11. `supports_color_blending`
12. `min_uniform_buffer_offset_alignment`
13. `min_storage_buffer_offset_alignment`
14. `min_texture_copy_bytes_per_row_alignment`

The three alignment fields are backend-agnostic numeric limits. They are required for scene/runtime
planning, but individual JSON fixtures do not need to declare them unless the fixture specifically
tests dynamic buffer offsets or texture-copy row-pitch alignment.

Weighted blended OIT is not represented as a single capability bit. The scene derives whether it can
use that technique from lower-level facts: at least two color attachments, supported floating-point
render-target formats for the accumulation targets, color blending support, and the ability to run
the needed transparent accumulation and resolve render passes.


## Active `2.0` Command Gates

The first active `2.0` capability validation rules are:

1. `CreateBuffer.size` must not exceed `max_buffer_size`,
2. `CreateTexture.format` must be listed in `supported_texture_formats`,
3. `CreateTexture.sample_count` must be listed in `supported_sample_counts`,
4. `CreateTexture` dimensions must not exceed the corresponding `max_texture_dimension_*` field for
   the chosen texture dimension,
5. `CreateShaderModule.format` must be listed in `supported_shader_formats` when that field is
   present,
6. a shader module declaring `required_features = ["fp64"]` requires `supports_fp64 = true`,
7. compute is mandatory in active DRP2 `2.0` and therefore is not gated by a capability field.

Capability failures should occur during `capability_validation` after schema and semantic validation
have succeeded.


## Feature Gating Rules

1. If a command needs a capability, that dependency must be explicit in the contract.
2. Unsupported features fail during capability validation, before backend submission.
3. Capability reports are declarative; they must not expose backend handle types.
4. WGSL should be the default shader language for the portable contract.
5. GLSL and native-only ingestion paths such as SPIR-V belong behind explicit capability flags in
   `supported_shader_formats`.


## Error Mapping

The first capability-validation mapping should be:

1. use `DRP2_ERR_UNSUPPORTED_CAPABILITY` when the runtime explicitly reports lack of support for a
   requested capability,
2. use `DRP2_ERR_FEATURE_REQUIRED` when the command stream requires a feature the runtime reports as
   unavailable and the fixture is explicitly testing that required feature boundary,
3. for the current active fixture corpus, prefer `DRP2_ERR_UNSUPPORTED_CAPABILITY`.


## FP64

FP64 should be treated as optional-but-reportable at the contract level.

Rules:

1. The capability report must state whether FP64 is supported.
2. Pipelines or shader modules that require FP64 must declare that requirement.
3. Producers must be able to select a fallback path when FP64 is unavailable.


## Determinism

The capability model should distinguish:

1. best-effort execution,
2. deterministic rendering and readback where guaranteed,
3. deterministic compute/reduction modes where explicitly supported.

Determinism should be requested by contract-level policy, not inferred from a backend.