deps(lambda-rs): Update to wgpu & naga to v28 and replace push constants with immediates #90

vmarcella · 2026-01-06T01:23:47Z

Summary

Update wgpu and naga dependencies from v26 to v28. This PR addresses breaking API changes and fully migrates from "push constants" to the new "immediates" API introduced in wgpu v28, including renaming all public APIs, types, and documentation to use the new terminology.

In wgpu v28, push constants were renamed to "immediates" and gated behind the Features::IMMEDIATES feature flag. This PR updates all engine code, public APIs, examples, tools, and tutorials to use the new API and consistent terminology.

Related Issues

Changes

wgpu v28 API Migration

PipelineLayoutDescriptor::push_constant_ranges → immediate_size: u32
RenderPipelineDescriptor::multiview → multiview_mask
DeviceDescriptor now requires experimental_features field
SamplerDescriptor::mipmap_filter uses separate MipmapFilterMode enum

Immediates Feature Enablement

Enable Features::IMMEDIATES by default in GPU builder
Add set_immediates(offset, data) method to platform RenderPass
Add set_immediates() to high-level RenderPassEncoder

Public API Renames (Breaking)

Platform layer (lambda-rs-platform):

PushConstantRange → ImmediateDataRange
PipelineLayoutBuilder::push_constant_ranges field → immediate_data_ranges
PipelineLayoutBuilder::with_push_constants() → with_immediate_data_ranges()

High-level API (lambda-rs):

PushConstantUpload type alias → ImmediateDataUpload
RenderPipelineBuilder::push_constants field → immediate_data
RenderPipelineBuilder::with_push_constant() → with_immediate_data()
RenderCommand::PushConstants variant removed (use RenderCommand::Immediates)

Updated Examples

push_constants.rs → immediates.rs
reflective_room.rs - migrated to ImmediateData, with_immediate_data(), RenderCommand::Immediates
textured_cube.rs - migrated to ImmediateData, with_immediate_data(), RenderCommand::Immediates
triangles.rs - migrated to ImmediateData, with_immediate_data(), RenderCommand::Immediates

Updated Tools

obj_loader - migrated to ImmediateData, with_immediate_data(), RenderCommand::Immediates

Updated Documentation

README.md - updated example name from "Push Constants" to "Immediates"

Updated Tutorials

push-constants-multiple-triangles.md → immediates-multiple-triangles.md
textured-cube.md - updated wgpu version, all with_push_constant() → with_immediate_data()
reflective-room.md - updated wgpu version, tags, terminology, all API calls
basic-triangle.md - updated exercise to reference "immediates" instead of "push constants"
uniform-buffers.md - updated exercise references

Type of Change

Bug fix (non-breaking change that fixes an issue)
Feature (non-breaking change that adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation (updates to docs, specs, tutorials, or comments)
Refactor (code change that neither fixes a bug nor adds a feature)
Performance (change that improves performance)
Test (adding or updating tests)
Build/CI (changes to build process or CI configuration)

Affected Crates

Checklist

Code follows the repository style guidelines (cargo +nightly fmt --all)
Code passes clippy (cargo clippy --workspace --all-targets -- -D warnings)
Tests pass (cargo test --workspace)
New code includes appropriate documentation
Public API changes are documented
Breaking changes are noted in this PR description

Testing

Commands run:

cargo build --workspace
cargo run -p lambda-rs --example immediates
cargo run -p lambda-rs --example triangles
cargo run -p lambda-rs --example textured_cube
cargo run -p lambda-rs --example reflective_room

Manual verification steps (if applicable):

Run the immediates example - window opens showing a rotating colored triangle
Run triangles example - multiple triangles render with keyboard control
Run textured_cube example - textured cube rotates on screen
Run reflective_room example - cube reflects on floor surface
Verify no crash occurs (previously crashed with "Capability Capabilities(IMMEDIATES) is not supported")

Screenshots/Recordings

The examples render correctly, demonstrating per-draw immediate data updates.

Platform Testing

macOS
Windows
Linux

Additional Notes

Breaking Changes

RenderCommand::PushConstants removed - All code must use RenderCommand::Immediates
with_push_constant() renamed - All code must use with_immediate_data()
PushConstantUpload renamed - Use ImmediateDataUpload type alias
Platform types renamed - PushConstantRange → ImmediateDataRange, with_push_constants() → with_immediate_data_ranges()

Migration Guide

1. Update pipeline builders:

// Before
RenderPipelineBuilder::new()
  .with_push_constant(PipelineStage::VERTEX, 64)
  .build(...)

// After
RenderPipelineBuilder::new()
  .with_immediate_data(PipelineStage::VERTEX, 64)
  .build(...)

2. Update render commands:

// Before
RenderCommand::PushConstants {
  pipeline,
  stage,
  offset,
  bytes,
}

// After
RenderCommand::Immediates {
  pipeline,
  stage,
  offset,
  bytes,
}

3. Rename data structs and helpers:

// Before
struct PushConstant { ... }
fn push_constants_to_bytes(...) { ... }

// After
struct ImmediateData { ... }
fn immediate_data_to_bytes(...) { ... }

…mplementation to use immediates.

Copilot

Pull request overview

This PR successfully migrates the lambda-rs rendering engine from wgpu v26 to v28, addressing the major breaking change where "push constants" were renamed to "immediates." The migration is comprehensive, updating not only the core engine code but also all examples, tools, tutorials, and documentation to reflect the new terminology and API changes.

Key Changes:

Updated wgpu dependency from v26.0.1 to v28.0.0 and naga from v26.0.0 to v28.0.0
Migrated from Features::PUSH_CONSTANTS to Features::IMMEDIATES with updated pipeline layout API (using immediate_size instead of push_constant_ranges)
Renamed all public APIs, types, and documentation from "push constants" terminology to "immediates"

Reviewed changes

Copilot reviewed 23 out of 24 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`Cargo.lock`	Updates wgpu ecosystem dependencies (wgpu, wgpu-core, wgpu-hal, wgpu-types, naga) from v26 to v28 along with transitive dependencies
`crates/lambda-rs-platform/Cargo.toml`	Updates naga to v28.0.0 and wgpu to v28.0.0 with reformatted feature declarations
`crates/lambda-rs-platform/src/wgpu/gpu.rs`	Replaces `Features::PUSH_CONSTANTS` with `Features::IMMEDIATES` and adds `experimental_features` field to device descriptor
`crates/lambda-rs-platform/src/wgpu/pipeline.rs`	Renames `PushConstantRange` to `ImmediateDataRange`, migrates pipeline layout from `push_constant_ranges` array to single `immediate_size` scalar, updates `multiview` to `multiview_mask`
`crates/lambda-rs-platform/src/wgpu/render_pass.rs`	Removes `set_push_constants` method, adds `set_immediates` method, adds `multiview_mask` field to render pass descriptor
`crates/lambda-rs-platform/src/wgpu/surface.rs`	Removes wildcard pattern from `PresentMode::from_wgpu` match (all variants now explicitly covered)
`crates/lambda-rs-platform/src/wgpu/texture.rs`	Adds `to_wgpu_mipmap` method returning `MipmapFilterMode` (separate from `FilterMode` in wgpu v28), updates sampler and test assertions
`crates/lambda-rs/src/render/gpu.rs`	Updates comment from "Push constants enabled" to "Immediates enabled"
`crates/lambda-rs/src/render/pipeline.rs`	Renames `PushConstantUpload` to `ImmediateDataUpload`, renames `push_constants` field to `immediate_data`, renames `with_push_constant` to `with_immediate_data`, updates platform layer calls
`crates/lambda-rs/src/render/mod.rs`	Updates comment references, implements `RenderCommand::Immediates` handler calling `set_immediates`
`crates/lambda-rs/src/render/encoder.rs`	Removes `set_push_constants` method, adds `set_immediates` method with documentation
`crates/lambda-rs/src/render/command.rs`	Renames `RenderCommand::PushConstants` to `RenderCommand::Immediates` with updated documentation
`crates/lambda-rs/examples/immediates.rs`	Renames types and functions from push constants to immediates, updates comments and window title
`crates/lambda-rs/examples/triangles.rs`	Migrates from `PushConstant` to `ImmediateData`, updates API calls to use `with_immediate_data` and `RenderCommand::Immediates`
`crates/lambda-rs/examples/textured_cube.rs`	Migrates from `PushConstant` to `ImmediateData`, updates comments and API calls throughout
`crates/lambda-rs/examples/reflective_room.rs`	Migrates from `PushConstant` to `ImmediateData`, renames helper function to `immediate_data_to_words`
`tools/obj_loader/src/main.rs`	Migrates from `PushConstant` to `ImmediateData` with updated comments and API calls
`docs/tutorials/textured-cube.md`	Comprehensive update: title, metadata, terminology change from push constants to immediates throughout, adds wgpu v28 feature notes
`docs/tutorials/reflective-room.md`	Updates metadata, terminology, and all code examples to use immediates instead of push constants
`docs/tutorials/immediates-multiple-triangles.md`	Renames from push-constants tutorial, updates all content to use immediates terminology with wgpu v28 notes
`docs/tutorials/basic-triangle.md`	Updates exercise references from push constants to immediates
`docs/tutorials/uniform-buffers.md`	Updates exercise references to point to immediates example
`docs/tutorials/README.md`	Updates tutorial index entry from "Push Constants" to "Immediates"
`README.md`	Updates example documentation from "Push Constants" to "Immediates", formatting improvements throughout

Comments suppressed due to low confidence (1)

docs/tutorials/immediates-multiple-triangles.md:6

The last_updated date is set to 2026-01-05, which is in the future. The current date according to the system context is January 6, 2026, so this date should be updated to reflect the actual update date or set to today's date (2026-01-06).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-06T01:27:50Z

crates/lambda-rs-platform/src/wgpu/pipeline.rs

+    // Calculate the total immediate size from immediate data ranges.
+    // The immediate_size is the maximum end offset across all ranges.
+    let immediate_size = self
+      .immediate_data_ranges
      .iter()
-      .map(|pcr| wgpu::PushConstantRange {
-        stages: pcr.stages.to_wgpu(),
-        range: pcr.range.clone(),
-      })
-      .collect();
+      .map(|r| r.range.end)
+      .max()
+      .unwrap_or(0);


The calculation of immediate_size only considers the maximum end offset, but does not verify that ranges start at 0 or are contiguous. In wgpu v28, immediate_size represents the total size of immediate data that must be allocated. If there are gaps in the ranges or if ranges don't start at 0, this calculation may produce an incorrect size. The implementation should either ensure ranges are validated to be contiguous starting from 0, or calculate the size differently to handle non-contiguous ranges.

Copilot · 2026-01-06T01:27:50Z

crates/lambda-rs/src/render/mod.rs

+        RenderCommand::Immediates {
+          pipeline: _,
+          stage: _,
          offset,
          bytes,
        } => {
-          let _ = render_pipelines.get(pipeline).ok_or_else(|| {
-            RenderPassError::Validation(format!("Unknown pipeline {pipeline}"))
-          })?;
-          let slice = unsafe {
+          // Convert the u32 words to a byte slice for set_immediates.
+          let byte_slice = unsafe {
            std::slice::from_raw_parts(
              bytes.as_ptr() as *const u8,
              bytes.len() * std::mem::size_of::<u32>(),
            )
          };
-          rp_encoder.set_push_constants(stage, offset, slice);
+          rp_encoder.set_immediates(offset, byte_slice);


The pipeline and stage fields in the RenderCommand::Immediates variant are ignored (marked with underscore). While the wgpu v28 set_immediates API no longer requires stage information at the call site, the pipeline field should still be validated to ensure it exists before attempting to set immediate data. Consider adding validation similar to the BindVertexBuffer command which validates the pipeline exists.

…hey're no longer required by wgpu.

vmarcella added 4 commits January 5, 2026 15:45

[update] engine to support wgpu 28 by converting the push constants i…

f4b9208

…mplementation to use immediates.

[rmeove] all push constants references and implementations.

5897499

[update] readme.

67c81a8

[update] documentation.

784542b

vmarcella requested a review from Copilot January 6, 2026 01:23

vmarcella added the dependencies Pull requests that update a dependency file label Jan 6, 2026

Copilot started reviewing on behalf of vmarcella January 6, 2026 01:24 View session

vmarcella changed the title ~~deps(lambda-rs): Update to wgpu & naga from 28 and replace push constants with immediates~~ deps(lambda-rs): Update to wgpu & naga to v28 and replace push constants with immediates Jan 6, 2026

Copilot AI reviewed Jan 6, 2026

View reviewed changes

vmarcella added 4 commits January 6, 2026 15:19

[add] explicit version for which windows crate to use.

d0ef986

[add] validation for imediate ranges.

9e4bd83

[add] pipeline validation back.

183a049

[remove] pipeline stages from being used when setting immediates as t…

ea79609

…hey're no longer required by wgpu.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

deps(lambda-rs): Update to wgpu & naga to v28 and replace push constants with immediates #90

deps(lambda-rs): Update to wgpu & naga to v28 and replace push constants with immediates #90

Uh oh!

vmarcella commented Jan 6, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 6, 2026

Uh oh!

Copilot AI Jan 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

deps(lambda-rs): Update to wgpu & naga to v28 and replace push constants with immediates #90

Are you sure you want to change the base?

deps(lambda-rs): Update to wgpu & naga to v28 and replace push constants with immediates #90

Uh oh!

Conversation

vmarcella commented Jan 6, 2026

Summary

Related Issues

Changes

wgpu v28 API Migration

Immediates Feature Enablement

Public API Renames (Breaking)

Updated Examples

Updated Tools

Updated Documentation

Updated Tutorials

Type of Change

Affected Crates

Checklist

Testing

Screenshots/Recordings

Platform Testing

Additional Notes

Breaking Changes

Migration Guide

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants