Rename instance_id & instance_custom_index to instance_index & instance_custom_data (#6780)

2025-12-08 21:26:17 +00:00 · 2025-02-06 06:23:22 +13:00 · 2025-02-06 06:23:22 +13:00 · d34707ec3f
commit d34707ec3f
parent 8fb94d9c08
20 changed files with 48 additions and 46 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -53,6 +53,8 @@ Bottom level categories:
 - Avoid using default features in many dependencies, etc. By Brody in [#7031](https://github.com/gfx-rs/wgpu/pull/7031)
 - Use `hashbrown` to simplify no-std support. By Brody in [#6938](https://github.com/gfx-rs/wgpu/pull/6938) & [#6925](https://github.com/gfx-rs/wgpu/pull/6925).
 - If you use Binding Arrays in a bind group, you may not use Dynamic Offset Buffers or Uniform Buffers in that bind group. By @cwfitzgerald in [#6811](https://github.com/gfx-rs/wgpu/pull/6811)
+- Rename `instance_id` and `instance_custom_index` to `instance_index` and `instance_custom_data` by @Vecvec in
+  [#6780](https://github.com/gfx-rs/wgpu/pull/6780)

 ##### Refactored internal trace path parameter

--- a/etc/specs/ray_tracing.md
+++ b/etc/specs/ray_tracing.md
@ -109,11 +109,11 @@ struct RayIntersection {
    kind: u32,
    // Distance from starting point, measured in units of `RayDesc::dir`.
    t: f32,
-    // Corresponds to `instance.custom_index` where `instance` is the `TlasInstance`
+    // Corresponds to `instance.custom_data` where `instance` is the `TlasInstance`
    // that the intersected object was contained in.
-    instance_custom_index: u32,
+    instance_custom_data: u32,
    // The index into the `TlasPackage` to get the `TlasInstance` that the hit object is in
-    instance_id: u32,
+    instance_index: u32,
    // The offset into the shader binding table. Currently, this value is always 0.
    sbt_record_offset: u32,
    // The index into the `Blas`'s build descriptor (e.g. if `BlasBuildEntry::geometry` is
--- a/examples/features/src/ray_cube_compute/shader.wgsl
+++ b/examples/features/src/ray_cube_compute/shader.wgsl
@ -29,8 +29,8 @@ struct RayDesc {
 struct RayIntersection {
    kind: u32,
    t: f32,
-    instance_custom_index: u32,
-    instance_id: u32,
+    instance_custom_data: u32,
+    instance_index: u32,
    sbt_record_offset: u32,
    geometry_index: u32,
    primitive_index: u32,
--- a/examples/features/src/ray_scene/shader.wgsl
+++ b/examples/features/src/ray_scene/shader.wgsl
@ -52,8 +52,8 @@ struct RayDesc {
 struct RayIntersection {
    kind: u32,
    t: f32,
-    instance_custom_index: u32,
-    instance_id: u32,
+    instance_custom_data: u32,
+    instance_index: u32,
    sbt_record_offset: u32,
    geometry_index: u32,
    primitive_index: u32,
@ -131,7 +131,7 @@ fn fs_main(vertex: VertexOutput) -> @location(0) vec4<f32> {

    let intersection = rayQueryGetCommittedIntersection(&rq);
    if (intersection.kind != RAY_QUERY_INTERSECTION_NONE) {
-        let instance = instances[intersection.instance_custom_index];
+        let instance = instances[intersection.instance_custom_data];
        let geometry = geometries[intersection.geometry_index + instance.first_geometry];

        let index_offset = geometry.first_index;
@ -155,7 +155,7 @@ fn fs_main(vertex: VertexOutput) -> @location(0) vec4<f32> {

        color = vec4<f32>(material.albedo, 1.0);

-        if(intersection.instance_custom_index == 1u){
+        if(intersection.instance_custom_data == 1u){
            color = vec4<f32>(normal, 1.0);
        }
    }
--- a/naga/src/back/hlsl/ray.rs
+++ b/naga/src/back/hlsl/ray.rs
@ -42,11 +42,11 @@ impl<W: Write> super::Writer<'_, W> {
        writeln!(self.out, "        ret.t = rq.CommittedRayT();")?;
        writeln!(
            self.out,
-            "        ret.instance_custom_index = rq.CommittedInstanceID();"
+            "        ret.instance_custom_data = rq.CommittedInstanceID();"
        )?;
        writeln!(
            self.out,
-            "        ret.instance_id = rq.CommittedInstanceIndex();"
+            "        ret.instance_index = rq.CommittedInstanceIndex();"
        )?;
        writeln!(
            self.out,
@ -129,11 +129,11 @@ impl<W: Write> super::Writer<'_, W> {

        writeln!(
            self.out,
-            "    ret.instance_custom_index = rq.CandidateInstanceID();"
+            "    ret.instance_custom_data = rq.CandidateInstanceID();"
        )?;
        writeln!(
            self.out,
-            "    ret.instance_id = rq.CandidateInstanceIndex();"
+            "    ret.instance_index = rq.CandidateInstanceIndex();"
        )?;
        writeln!(
            self.out,
--- a/naga/src/front/type_gen.rs
+++ b/naga/src/front/type_gen.rs
@ -180,13 +180,13 @@ impl crate::Module {
                            offset: 4,
                        },
                        crate::StructMember {
-                            name: Some("instance_custom_index".to_string()),
+                            name: Some("instance_custom_data".to_string()),
                            ty: ty_flag,
                            binding: None,
                            offset: 8,
                        },
                        crate::StructMember {
-                            name: Some("instance_id".to_string()),
+                            name: Some("instance_index".to_string()),
                            ty: ty_flag,
                            binding: None,
                            offset: 12,
--- a/naga/tests/in/ray-query.wgsl
+++ b/naga/tests/in/ray-query.wgsl
@ -28,8 +28,8 @@ struct RayDesc {
 struct RayIntersection {
    kind: u32,
    t: f32,
-    instance_custom_index: u32,
-    instance_id: u32,
+    instance_custom_data: u32,
+    instance_index: u32,
    sbt_record_offset: u32,
    geometry_index: u32,
    primitive_index: u32,
--- a/naga/tests/out/hlsl/ray-query.hlsl
+++ b/naga/tests/out/hlsl/ray-query.hlsl
@ -1,8 +1,8 @@
 struct RayIntersection {
    uint kind;
    float t;
-    uint instance_custom_index;
-    uint instance_id;
+    uint instance_custom_data;
+    uint instance_index;
    uint sbt_record_offset;
    uint geometry_index;
    uint primitive_index;
@ -64,8 +64,8 @@ RayIntersection GetCommittedIntersection(RayQuery<RAY_FLAG_NONE> rq) {
    ret.kind = rq.CommittedStatus();
    if( rq.CommittedStatus() == COMMITTED_NOTHING) {} else {
        ret.t = rq.CommittedRayT();
-        ret.instance_custom_index = rq.CommittedInstanceID();
-        ret.instance_id = rq.CommittedInstanceIndex();
+        ret.instance_custom_data = rq.CommittedInstanceID();
+        ret.instance_index = rq.CommittedInstanceIndex();
        ret.sbt_record_offset = rq.CommittedInstanceContributionToHitGroupIndex();
        ret.geometry_index = rq.CommittedGeometryIndex();
        ret.primitive_index = rq.CommittedPrimitiveIndex();
@ -131,8 +131,8 @@ RayIntersection GetCandidateIntersection(RayQuery<RAY_FLAG_NONE> rq) {
    } else {
        ret.kind = 3;
    }
-    ret.instance_custom_index = rq.CandidateInstanceID();
-    ret.instance_id = rq.CandidateInstanceIndex();
+    ret.instance_custom_data = rq.CandidateInstanceID();
+    ret.instance_index = rq.CandidateInstanceIndex();
    ret.sbt_record_offset = rq.CandidateInstanceContributionToHitGroupIndex();
    ret.geometry_index = rq.CandidateGeometryIndex();
    ret.primitive_index = rq.CandidatePrimitiveIndex();
--- a/naga/tests/out/msl/ray-query.msl
+++ b/naga/tests/out/msl/ray-query.msl
@ -16,8 +16,8 @@ constexpr metal::uint _map_intersection_type(const metal::raytracing::intersecti
 struct RayIntersection {
    uint kind;
    float t;
-    uint instance_custom_index;
-    uint instance_id;
+    uint instance_custom_data;
+    uint instance_index;
    uint sbt_record_offset;
    uint geometry_index;
    uint primitive_index;
--- a/player/src/lib.rs
+++ b/player/src/lib.rs
@ -194,7 +194,7 @@ impl GlobalPlay for wgc::global::Global {
                                .map(|instance| wgc::ray_tracing::TlasInstance {
                                    blas_id: instance.blas_id,
                                    transform: &instance.transform,
-                                    custom_index: instance.custom_index,
+                                    custom_data: instance.custom_data,
                                    mask: instance.mask,
                                })
                        });
--- a/tests/tests/ray_tracing/shader.wgsl
+++ b/tests/tests/ray_tracing/shader.wgsl
@ -4,8 +4,8 @@ var acc_struct: acceleration_structure;
 struct Intersection {
    kind: u32,
    t: f32,
-    instance_custom_index: u32,
-    instance_id: u32,
+    instance_custom_data: u32,
+    instance_index: u32,
    sbt_record_offset: u32,
    geometry_index: u32,
    primitive_index: u32,
@ -38,8 +38,8 @@ fn all_of_struct() {
    out = Intersection(
        intersection.kind,
        intersection.t,
-        intersection.instance_custom_index,
-        intersection.instance_id,
+        intersection.instance_custom_data,
+        intersection.instance_index,
        intersection.sbt_record_offset,
        intersection.geometry_index,
        intersection.primitive_index,
--- a/wgpu-core/src/command/ray_tracing.rs
+++ b/wgpu-core/src/command/ray_tracing.rs
@ -396,7 +396,7 @@ impl Global {
                        instance.map(|instance| TraceTlasInstance {
                            blas_id: instance.blas_id,
                            transform: *instance.transform,
-                            custom_index: instance.custom_index,
+                            custom_data: instance.custom_data,
                            mask: instance.mask,
                        })
                    })
@ -444,7 +444,7 @@ impl Global {
                instance.as_ref().map(|instance| TlasInstance {
                    blas_id: instance.blas_id,
                    transform: &instance.transform,
-                    custom_index: instance.custom_index,
+                    custom_data: instance.custom_data,
                    mask: instance.mask,
                })
            });
@ -512,7 +512,7 @@ impl Global {

            let mut instance_count = 0;
            for instance in package.instances.flatten() {
-                if instance.custom_index >= (1u32 << 24u32) {
+                if instance.custom_data >= (1u32 << 24u32) {
                    return Err(BuildAccelerationStructureError::TlasInvalidCustomIndex(
                        tlas.error_ident(),
                    ));
@ -524,7 +524,7 @@ impl Global {
                instance_buffer_staging_source.extend(device.raw().tlas_instance_to_bytes(
                    hal::TlasInstance {
                        transform: *instance.transform,
-                        custom_index: instance.custom_index,
+                        custom_data: instance.custom_data,
                        mask: instance.mask,
                        blas_address: blas.handle,
                    },
--- a/wgpu-core/src/ray_tracing.rs
+++ b/wgpu-core/src/ray_tracing.rs
@ -175,7 +175,7 @@ pub struct TlasBuildEntry {
 pub struct TlasInstance<'a> {
    pub blas_id: BlasId,
    pub transform: &'a [f32; 12],
-    pub custom_index: u32,
+    pub custom_data: u32,
    pub mask: u8,
 }

@ -243,7 +243,7 @@ pub struct TraceBlasBuildEntry {
 pub struct TraceTlasInstance {
    pub blas_id: BlasId,
    pub transform: [f32; 12],
-    pub custom_index: u32,
+    pub custom_data: u32,
    pub mask: u8,
 }

--- a/wgpu-hal/examples/ray-traced-triangle/main.rs
+++ b/wgpu-hal/examples/ray-traced-triangle/main.rs
@ -33,7 +33,7 @@ impl std::fmt::Debug for AccelerationStructureInstance {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Instance")
            .field("transform", &self.transform)
-            .field("custom_index()", &self.custom_index())
+            .field("custom_data()", &self.custom_index())
            .field("mask()", &self.mask())
            .field(
                "shader_binding_table_record_offset()",
--- a/wgpu-hal/src/dx12/device.rs
+++ b/wgpu-hal/src/dx12/device.rs
@ -2316,7 +2316,7 @@ impl crate::Device for super::Device {
        const MAX_U24: u32 = (1u32 << 24u32) - 1u32;
        let temp = Direct3D12::D3D12_RAYTRACING_INSTANCE_DESC {
            Transform: instance.transform,
-            _bitfield1: (instance.custom_index & MAX_U24) | (u32::from(instance.mask) << 24),
+            _bitfield1: (instance.custom_data & MAX_U24) | (u32::from(instance.mask) << 24),
            _bitfield2: 0,
            AccelerationStructure: instance.blas_address,
        };
--- a/wgpu-hal/src/lib.rs
+++ b/wgpu-hal/src/lib.rs
@ -2444,7 +2444,7 @@ pub struct AccelerationStructureBarrier {
 #[derive(Debug, Copy, Clone)]
 pub struct TlasInstance {
    pub transform: [f32; 12],
-    pub custom_index: u32,
+    pub custom_data: u32,
    pub mask: u8,
    pub blas_address: u64,
 }
--- a/wgpu-hal/src/vulkan/device.rs
+++ b/wgpu-hal/src/vulkan/device.rs
@ -2569,7 +2569,7 @@ impl crate::Device for super::Device {
        const MAX_U24: u32 = (1u32 << 24u32) - 1u32;
        let temp = RawTlasInstance {
            transform: instance.transform,
-            custom_index_and_mask: (instance.custom_index & MAX_U24)
+            custom_data_and_mask: (instance.custom_data & MAX_U24)
                | (u32::from(instance.mask) << 24),
            shader_binding_table_record_offset_and_flags: 0,
            acceleration_structure_reference: instance.blas_address,
--- a/wgpu-hal/src/vulkan/mod.rs
+++ b/wgpu-hal/src/vulkan/mod.rs
@ -1480,7 +1480,7 @@ fn get_lost_err() -> crate::DeviceError {
 #[repr(C)]
 struct RawTlasInstance {
    transform: [f32; 12],
-    custom_index_and_mask: u32,
+    custom_data_and_mask: u32,
    shader_binding_table_record_offset_and_flags: u32,
    acceleration_structure_reference: u64,
 }
--- a/wgpu/src/api/blas.rs
+++ b/wgpu/src/api/blas.rs
@ -49,7 +49,7 @@ pub struct TlasInstance {
    ///
    /// This must only use the lower 24 bits, if any bits are outside that range (byte 4 does not equal 0) the TlasInstance becomes
    /// invalid and generates a validation error when built
-    pub custom_index: u32,
+    pub custom_data: u32,
    /// Mask for the instance used inside the shader to filter instances.
    /// Reports hit only if `(shader_cull_mask & tlas_instance.mask) != 0u`.
    pub mask: u8,
@ -59,7 +59,7 @@ impl TlasInstance {
    /// Construct TlasInstance.
    /// - blas: Reference to the bottom level acceleration structure
    /// - transform: Transform buffer offset in bytes (optional, required if transform buffer is present)
-    /// - custom_index: Custom index for the instance used inside the shader (max 24 bits)
+    /// - custom_data: Custom index for the instance used inside the shader (max 24 bits)
    /// - mask: Mask for the instance used inside the shader to filter instances
    ///
    /// Note: while one of these contains a reference to a BLAS that BLAS will not be dropped,
@ -67,11 +67,11 @@ impl TlasInstance {
    /// TlasInstance(s) will immediately make them invalid. If one or more of those invalid
    /// TlasInstances is inside a TlasPackage that is attempted to be built, the build will
    /// generate a validation error.
-    pub fn new(blas: &Blas, transform: [f32; 12], custom_index: u32, mask: u8) -> Self {
+    pub fn new(blas: &Blas, transform: [f32; 12], custom_data: u32, mask: u8) -> Self {
        Self {
            blas: blas.inner.clone(),
            transform,
-            custom_index,
+            custom_data,
            mask,
        }
    }
--- a/wgpu/src/backend/wgpu_core.rs
+++ b/wgpu/src/backend/wgpu_core.rs
@ -2522,7 +2522,7 @@ impl dispatch::CommandEncoderInterface for CoreCommandEncoder {
                        .map(|instance| wgc::ray_tracing::TlasInstance {
                            blas_id: instance.blas.as_core().id,
                            transform: &instance.transform,
-                            custom_index: instance.custom_index,
+                            custom_data: instance.custom_data,
                            mask: instance.mask,
                        })
                });