[SYCL][Bindless][UR] Add support for sRGB image formats

[juanchuletas]

Summary

This PR adds native sRGB decode support for bindless images through the full DPC++ stack: SYCL API, Unified Runtime, and the Level Zero adapter.

Description

The hardware sampler on Intel Arc GPUs supports native sRGB decode via ze_srgb_ext_desc_t, confirmed by direct Level Zero testing against driver 26.18.38308.1. The driver correctly applies the IEC 61966-2-1 piecewise formula on fetch, returning linear values to the kernel. This capability was not exposed anywhere in the DPC++ or UR stack.

The SYCL bindless image API had no way to request sRGB color space decoding. The image_descriptor only accepted num_channels and channel_type, with the channel order always derived internally. This made it impossible to distinguish between a linear RGBA texture and an sRGB-encoded RGBA texture, forcing applications to manually decode sRGB values on the CPU before upload at a significant memory cost.

Proposed Changes

sycl/include/sycl/ext/oneapi/bindless_images_descriptor.hpp

Added an std::optional<image_channel_order> channel order field to image_descriptor. This defaults to std::nullopt to preserve full backward compatibility. Added a validation check in verify() to ensure that when channel_order is set to ext_oneapi_srgba, the configuration must use 4 channels and the unorm_int8 type, as these are the only values accepted by the Level Zero driver for sRGB images.

sycl/source/detail/bindless_images.cpp

Modified populate_ur_structs to use the provided channel order via channel_order.value_or(get_image_default_channel_order(num_channels)). When the channel order is not set, the behavior remains identical to previous versions. When set, the explicit value is passed to the Unified Runtime.

unified-runtime/source/adapters/level_zero/image_common.cpp

Updated ur2zeImageDesc to map UR_IMAGE_CHANNEL_ORDER_SRGBA to the ZE_IMAGE_FORMAT_LAYOUT_8_8_8_8 memory layout. Configured the hardware channel assignment for SRGBA to maintain a 1-to-1 mapping, identical to the standard RGBA configuration.

Modified urBindlessImagesImageAllocateExp to append ze_srgb_ext_desc_t (with sRGB = true) to the ZeImageBindlessDesc.pNext chain when UR_IMAGE_CHANNEL_ORDER_SRGBA is specified. This forces the hardware to enable the sRGB-to-Linear conversion path during image fetches.

Modified bindlessImagesCreateImpl to chain ze_srgb_ext_desc_t correctly for both sampled and unsampled image paths, ensuring the existing pNext chain order is respected: ZeImageDesc -> BindlessDesc -> ZeSrgbDesc -> ZeSamplerDesc.

Proposed Usage

sycl::ext::oneapi::experimental::image_descriptor desc(
    sycl::range<2>(width, height),
    4,
    sycl::image_channel_type::unorm_int8
);
desc.channel_order = sycl::image_channel_order::ext_oneapi_srgba;

sycl::ext::oneapi::experimental::image_mem imgMem(desc, q);

[juanchuletas]

Update,

I tested the changes using:

srgb_vs_rgb.cpp

and I got:

Device: Intel(R) Arc(TM) Graphics

Input raw pixel value:            186 (0xba)
Input normalized (unorm_int8):    0.729412
Expected linear :  0.491021

RGBA  result (no decode):  R=0.729412 G=0.729412 B=0.729412 A=1
sRGBA result (hardware decoded): R=0.490745 G=0.490745 B=0.490745 A=1

Difference in R channel:   0.238666

PASS: RGBA returns raw unorm, sRGBA returns decoded linear

[kswiecicki]

L0 adapter side LGTM, 2 nitpicks.

[0x12CC]

Thanks, @juanchuletas. Please add relevant tests.

[0x12CC]

These changes need corresponding changes in sycl/doc/extensions/experimental/sycl_ext_oneapi_bindless_images.asciidoc to ensure the implementation and specification remain consistent.

[juanchuletas]

@0x12CC @kswiecicki

I was thinking about the current implementation and some scenarios came out. The current implementation exposes channel_order as an std::optional<image_channel_order> on image_descriptor.

Nothing stops the user from doing the following:

sycl::ext::oneapi::experimental::image_descriptor desc(
    sycl::range<2>(width, height),
    4,
    sycl::image_channel_type::unorm_int8
);
desc.channel_order = sycl::image_channel_order::rgx;

We can prohibit that kind of usage from the verify() method

if (channel_order.has_value()) {
  if (channel_order.value() != image_channel_order::ext_oneapi_srgba) {
    throw sycl::exception(
        sycl::errc::invalid,
        "channel_order only supports ext_oneapi_srgba");
  }
  if (num_channels != 4) {
    throw sycl::exception(
        sycl::errc::invalid,
        "ext_oneapi_srgba channel order requires num_channels == 4");
  }
  if (channel_type != image_channel_type::unorm_int8) {
    throw sycl::exception(
        sycl::errc::invalid,
        "ext_oneapi_srgba channel order requires unorm_int8 channel type");
  }
}

but it feels weird to expose desc.channel_order and only allowing srgb. Other approach is to Make channel_order fully general: validate channel count consistency in verify() for any value set.

[dyniols]

This PR is ABI breaking because of changes in image_descriptor struct layout.

I wonder if we could re-work image_descriptor back to support channel_order since it was replaced with num_channels due to lack of support in CUDA.
Here is PR when this change was introduced: #13745
I believe that Level Zero, OpenCL backend should support channel order.

Please add tests exercising the new sRGB path with sampled, unsampled and using pitched memory allocation, through pitched_alloc_device.

[dyniols]

nit: re-align the include comments and add // for std::optional.

[juanchuletas]

This PR is ABI breaking because of changes in image_descriptor struct layout.

I wonder if we could re-work image_descriptor back to support channel_order since it was replaced with num_channels due to lack of support in CUDA. Here is PR when this change was introduced: #13745 I believe that Level Zero, OpenCL backend should support channel order.

Please add tests exercising the new sRGB path with sampled, unsampled and using pitched memory allocation, through pitched_alloc_device.

This PR is ABI breaking because of changes in image_descriptor struct layout.

I wonder if we could re-work image_descriptor back to support channel_order since it was replaced with num_channels due to lack of support in CUDA. Here is PR when this change was introduced: #13745 I believe that Level Zero, OpenCL backend should support channel order.

Please add tests exercising the new sRGB path with sampled, unsampled and using pitched memory allocation, through pitched_alloc_device.

Given that restoring channel_order as a primary field would also be an ABI break, and that CUDA does not support channel order natively, what is the preferred approach?

• replacement of num_channels with channel_order

• stay focused on sRGB hardware decode only

I am open to work on any of the approaches

[dyniols]

Given that restoring channel_order as a primary field would also be an ABI break.

I don't think the ABI break is avoidable here. Naturally, a change like this should land with the next major release. In the meantime, we can leverage __INTEL_PREVIEW_BREAKING_CHANGES macro to merge ABI-breaking change without delay and then remove it when possible.

what is the preferred approach?

• replacement of num_channels with channel_order
• stay focused on sRGB hardware decode only

I am open to work on any of the approaches

I lean towards replacement of num_channels with channel_order and using with image_channel_order enum class.
However I would ask @0x12CC on his perspective on such a change.