wgpu 1.0.0 → 1.2.0

data/lib/wgpu/core/device.rb

@@ -4,21 +4,26 @@ module WGPU
   class Device
     attr_reader :handle, :queue, :adapter
 
-    CALLBACK_MODE_WAIT_ANY_ONLY = 1
     LIMIT_FIELDS = Native::Limits.members.freeze
 
-    def self.request(adapter, label: nil, required_features: [], required_limits: nil)
+    def self.request(adapter, label: nil, required_features: [], required_limits: nil, timeout: nil)
       device_ptr = FFI::MemoryPointer.new(:pointer)
-      status_holder = { value: nil, message: nil }
+      status_holder = { done: false, value: nil, message: nil }
+      device_callback_state = {
+        mutex: Mutex.new,
+        uncaptured_error: nil,
+        device_lost: nil
+      }
 
       callback = FFI::Function.new(
-        :void, [:uint32, :pointer, Native::StringView.by_value, :pointer]
-      ) do |status, device, message, _userdata|
+        :void, [:uint32, :pointer, Native::StringView.by_value, :pointer, :pointer]
+      ) do |status, device, message, _userdata1, _userdata2|
         status_holder[:value] = Native::RequestDeviceStatus[status]
         if message[:data] && !message[:data].null? && message[:length] > 0
           status_holder[:message] = message[:data].read_string(message[:length])
         end
         device_ptr.write_pointer(device)
+        status_holder[:done] = true
       end
 
       queue_desc = Native::QueueDescriptor.new
@@ -28,14 +33,18 @@ module WGPU
 
       device_lost_info = Native::DeviceLostCallbackInfo.new
       device_lost_info[:next_in_chain] = nil
-      device_lost_info[:mode] = 0
-      device_lost_info[:callback] = nil
-      device_lost_info[:userdata] = nil
+      device_lost_info[:mode] = AsyncWaiter.callback_mode(instance: adapter.instance)
+      device_lost_callback = build_device_lost_callback(device_callback_state)
+      device_lost_info[:callback] = device_lost_callback
+      device_lost_info[:userdata1] = nil
+      device_lost_info[:userdata2] = nil
 
       error_info = Native::UncapturedErrorCallbackInfo.new
       error_info[:next_in_chain] = nil
-      error_info[:callback] = nil
-      error_info[:userdata] = nil
+      uncaptured_error_callback = build_uncaptured_error_callback(device_callback_state)
+      error_info[:callback] = uncaptured_error_callback
+      error_info[:userdata1] = nil
+      error_info[:userdata2] = nil
 
       desc = Native::DeviceDescriptor.new
       desc[:next_in_chain] = nil
@@ -67,11 +76,23 @@ module WGPU
 
       callback_info = Native::RequestDeviceCallbackInfo.new
       callback_info[:next_in_chain] = nil
-      callback_info[:mode] = CALLBACK_MODE_WAIT_ANY_ONLY
+      callback_info[:mode] = AsyncWaiter.callback_mode(instance: adapter.instance)
       callback_info[:callback] = callback
-      callback_info[:userdata] = nil
+      callback_info[:userdata1] = nil
+      callback_info[:userdata2] = nil
 
-      Native.wgpuAdapterRequestDevice(adapter.handle, desc, callback_info)
+      callback_token = CallbackKeepalive.retain(adapter, callback)
+      begin
+        future = Native.wgpuAdapterRequestDevice(adapter.handle, desc, callback_info)
+        AsyncWaiter.wait(
+          status_holder: status_holder,
+          instance: adapter.instance,
+          future: future,
+          timeout: timeout
+        )
+      ensure
+        CallbackKeepalive.release(adapter, callback_token)
+      end
 
       handle = device_ptr.read_pointer
       if handle.null? || status_holder[:value] != :success
@@ -79,12 +100,22 @@ module WGPU
         raise DeviceError, "Failed to request device: #{msg}"
       end
 
-      new(handle, adapter: adapter)
+      device = new(handle, adapter: adapter, label: label, callback_state: device_callback_state)
+      device.send(:retain_device_callback, device_lost_callback)
+      device.send(:retain_device_callback, uncaptured_error_callback)
+      device
     end
 
-    def initialize(handle, adapter: nil)
+    def initialize(handle, adapter: nil, label: nil, callback_state: nil)
       @handle = handle
       @adapter = adapter
+      @label = label
+      @device_callback_state = callback_state || {
+        mutex: Mutex.new,
+        uncaptured_error: nil,
+        device_lost: nil
+      }
+      @device_callback_tokens = []
       @queue = Queue.new(Native.wgpuDeviceGetQueue(@handle), device: self)
     end
 
@@ -96,8 +127,15 @@ module WGPU
       Buffer.new(self, label: label, size: size, usage: usage, mapped_at_creation: mapped_at_creation)
     end
 
-    def create_shader_module(label: nil, code:, compilation_hints: [])
-      ShaderModule.new(self, label: label, code: code, compilation_hints: compilation_hints)
+    def create_shader_module(label: nil, code: nil, spirv: nil, compilation_hints: [], validate: false)
+      ShaderModule.new(
+        self,
+        label: label,
+        code: code,
+        spirv: spirv,
+        compilation_hints: compilation_hints,
+        validate: validate
+      )
     end
 
     def create_command_encoder(label: nil)
@@ -181,8 +219,9 @@ module WGPU
       )
     end
 
-    def create_buffer_with_data(label: nil, data:, usage:)
-      data_ptr, byte_size = data_to_pointer(data)
+    def create_buffer_with_data(label: nil, data:, usage:, type: :f32)
+      data_ptr, byte_size = DataTypes.to_pointer(data, type:)
+      DataTypes.validate_alignment!(byte_size, 4, name: "buffer data size")
       buffer = create_buffer(
         label: label,
         size: byte_size,
@@ -235,19 +274,27 @@ module WGPU
     end
 
     def poll(wait: false)
-      Native.wgpuDevicePoll(@handle, wait ? 1 : 0, nil)
+      if Native.device_poll_available?
+        Native.wgpuDevicePoll(@handle, wait ? 1 : 0, nil)
+      else
+        @adapter&.instance&.process_events
+        0
+      end
     end
 
     def push_error_scope(filter = :validation)
-      Native.wgpuDevicePushErrorScope(@handle, filter)
+      filter_value = Native::EnumHelper.coerce(Native::ErrorFilter, filter, name: "error filter")
+      Native.wgpuDevicePushErrorScope(@handle, filter_value)
     end
 
-    def pop_error_scope
-      error_holder = { type: nil, message: nil }
+    def pop_error_scope(timeout: nil)
+      error_holder = { done: false, status: nil, type: nil, message: nil }
 
       callback = FFI::Function.new(
         :void, [:uint32, :uint32, Native::StringView.by_value, :pointer, :pointer]
-      ) do |_status, error_type, message, _userdata1, _userdata2|
+      ) do |status, error_type, message, _userdata1, _userdata2|
+        error_holder[:done] = true
+        error_holder[:status] = Native::PopErrorScopeStatus[status]
         error_holder[:type] = Native::ErrorType[error_type]
         if message[:data] && !message[:data].null? && message[:length] > 0
           error_holder[:message] = message[:data].read_string(message[:length])
@@ -256,30 +303,58 @@ module WGPU
 
       callback_info = Native::PopErrorScopeCallbackInfo.new
       callback_info[:next_in_chain] = nil
-      callback_info[:mode] = 1
+      callback_info[:mode] = AsyncWaiter.callback_mode(instance: @adapter&.instance)
       callback_info[:callback] = callback
       callback_info[:userdata1] = nil
       callback_info[:userdata2] = nil
 
-      Native.wgpuDevicePopErrorScope(@handle, callback_info)
+      callback_token = CallbackKeepalive.retain(self, callback)
+      begin
+        future = Native.wgpuDevicePopErrorScope(@handle, callback_info)
+        AsyncWaiter.wait(
+          status_holder: error_holder,
+          instance: @adapter&.instance,
+          device: self,
+          future: future,
+          timeout: timeout
+        )
+      ensure
+        CallbackKeepalive.release(self, callback_token)
+      end
 
       error_holder
     end
 
-    def pop_error_scope_async
-      AsyncTask.new { pop_error_scope }
+    def pop_error_scope_async(timeout: nil)
+      AsyncTask.new { pop_error_scope(timeout: timeout) }
+    end
+
+    def pop_error_scope_typed(timeout: nil)
+      GPUError.from_hash(pop_error_scope(timeout: timeout))
     end
 
     def with_error_scope(filter = :validation)
       push_error_scope(filter)
       result = yield
-      error = pop_error_scope
-      if error[:type] && error[:type] != :no_error
-        raise Error, "GPU error (#{error[:type]}): #{error[:message]}"
-      end
+      error = GPUError.from_hash(pop_error_scope)
+      error&.raise!
       result
     end
 
+    def on_uncaptured_error(&handler)
+      raise ArgumentError, "on_uncaptured_error requires a block" unless handler
+
+      set_device_callback(:uncaptured_error, handler)
+      self
+    end
+
+    def on_device_lost(&handler)
+      raise ArgumentError, "on_device_lost requires a block" unless handler
+
+      set_device_callback(:device_lost, handler)
+      self
+    end
+
     def destroy
       return if @handle.null?
       Native.wgpuDeviceDestroy(@handle)
@@ -290,10 +365,10 @@ module WGPU
       return if @handle.null?
       Native.wgpuDeviceRelease(@handle)
       @handle = FFI::Pointer::NULL
+      Array(@device_callback_tokens).each { |token| CallbackKeepalive.release(self, token) }
+      @device_callback_tokens&.clear
     end
 
-    private
-
     def self.normalize_required_features(required_features)
       Array(required_features).map do |feature|
         normalize_feature_name(feature)
@@ -304,10 +379,7 @@ module WGPU
       return feature if feature.is_a?(Integer)
 
       key = feature.to_s.strip.tr("-", "_").to_sym
-      value = Native::FeatureName[key]
-      raise ArgumentError, "Unknown feature name: #{feature}" if value.nil?
-
-      value
+      Native::EnumHelper.coerce(Native::FeatureName, key, name: "feature name")
     end
 
     def self.build_required_limits(adapter, required_limits)
@@ -340,23 +412,59 @@ module WGPU
       raise ArgumentError, "Unknown limit key: #{name}"
     end
 
-    def data_to_pointer(data)
-      case data
-      when String
-        ptr = FFI::MemoryPointer.new(:char, data.bytesize)
-        ptr.put_bytes(0, data)
-        [ptr, data.bytesize]
-      when Array
-        ptr = FFI::MemoryPointer.new(:float, data.size)
-        ptr.write_array_of_float(data)
-        [ptr, data.size * 4]
-      when FFI::Pointer
-        [data, data.size]
-      else
-        raise ArgumentError, "Unsupported data type: #{data.class}"
+    def self.build_uncaptured_error_callback(state)
+      FFI::Function.new(
+        :void, [:pointer, :uint32, Native::StringView.by_value, :pointer, :pointer]
+      ) do |_device, type, message, _userdata1, _userdata2|
+        error = GPUError.new(
+          type: Native::ErrorType[type] || :unknown,
+          message: string_from_callback(message)
+        )
+        dispatch_device_callback(state, :uncaptured_error, error) do
+          warn "Uncaptured GPU error (#{error.type}): #{error.message}"
+        end
       end
     end
 
+    def self.build_device_lost_callback(state)
+      FFI::Function.new(
+        :void, [:pointer, :uint32, Native::StringView.by_value, :pointer, :pointer]
+      ) do |_device, reason, message, _userdata1, _userdata2|
+        reason_name = Native::DeviceLostReason[reason] || :unknown
+        message_text = string_from_callback(message)
+        dispatch_device_callback(state, :device_lost, reason_name, message_text) do
+          warn "GPU device lost (#{reason_name}): #{message_text}" unless reason_name == :destroyed
+        end
+      end
+    end
+
+    def self.dispatch_device_callback(state, key, *args)
+      handler = state[:mutex].synchronize { state[key] }
+      handler ? handler.call(*args) : yield
+    rescue StandardError => e
+      warn "WGPU #{key} handler failed: #{e.class}: #{e.message}"
+    end
+
+    def self.string_from_callback(message)
+      return "" if message[:data].nil? || message[:data].null? || message[:length].zero?
+
+      message[:data].read_string(message[:length])
+    end
+
+    private_class_method :normalize_required_features, :normalize_feature_name,
+      :build_required_limits, :canonical_limit_key, :build_uncaptured_error_callback,
+      :build_device_lost_callback, :dispatch_device_callback, :string_from_callback
+
+    private
+
+    def retain_device_callback(callback)
+      @device_callback_tokens << CallbackKeepalive.retain(self, callback)
+    end
+
+    def set_device_callback(name, handler)
+      @device_callback_state[:mutex].synchronize { @device_callback_state[name] = handler }
+    end
+
     def limits_to_hash(limits)
       {
         max_texture_dimension_1d: limits[:max_texture_dimension_1d],

data/lib/wgpu/core/instance.rb

@@ -15,25 +15,29 @@ module WGPU
       raise InitializationError, "Failed to create WebGPU instance" if @handle.null?
     end
 
-    def request_adapter(power_preference: :high_performance, backend: nil, feature_level: :core, force_fallback_adapter: false, compatible_surface: nil)
+    def request_adapter(power_preference: :high_performance, backend: nil, feature_level: :core,
+                        force_fallback_adapter: false, compatible_surface: nil, timeout: nil)
       Adapter.request(
         self,
         power_preference: power_preference,
         backend: backend,
         feature_level: feature_level,
         force_fallback_adapter: force_fallback_adapter,
-        compatible_surface: compatible_surface
+        compatible_surface: compatible_surface,
+        timeout: timeout
       )
     end
 
-    def request_adapter_async(power_preference: :high_performance, backend: nil, feature_level: :core, force_fallback_adapter: false, compatible_surface: nil)
+    def request_adapter_async(power_preference: :high_performance, backend: nil, feature_level: :core,
+                              force_fallback_adapter: false, compatible_surface: nil, timeout: nil)
       AsyncTask.new do
         request_adapter(
           power_preference: power_preference,
           backend: backend,
           feature_level: feature_level,
           force_fallback_adapter: force_fallback_adapter,
-          compatible_surface: compatible_surface
+          compatible_surface: compatible_surface,
+          timeout: timeout
         )
       end
     end
@@ -53,7 +57,7 @@ module WGPU
       Native.wgpuInstanceEnumerateAdapters(@handle, options, adapters_ptr)
 
       adapters_ptr.read_array_of_pointer(count).map do |ptr|
-        Adapter.from_handle(ptr)
+        Adapter.from_handle(ptr, instance: self)
       end
     end
 

data/lib/wgpu/core/queue.rb

@@ -13,15 +13,24 @@ module WGPU
       buffers = Array(command_buffers)
       return if buffers.empty?
 
+      if buffers.map(&:object_id).uniq.length != buffers.length
+        raise CommandError, "The same command buffer cannot appear twice in one submission"
+      end
+      buffers.each do |buffer|
+        raise CommandError, "Command buffer has already been submitted" if buffer.submitted?
+      end
+
       handles = buffers.map(&:handle)
       ptr = FFI::MemoryPointer.new(:pointer, handles.size)
       ptr.write_array_of_pointer(handles)
 
       Native.wgpuQueueSubmit(@handle, handles.size, ptr)
+      buffers.each(&:mark_submitted!)
     end
 
-    def write_buffer(buffer, buffer_offset, data, data_offset: 0, size: nil)
-      data_ptr, byte_size = data_to_pointer(data)
+    def write_buffer(buffer, buffer_offset, data, data_offset: 0, size: nil, type: :f32)
+      data_ptr, byte_size = DataTypes.to_pointer(data, type:)
+      DataTypes.validate_alignment!(buffer_offset, 4, name: "buffer_offset")
       data_offset = Integer(data_offset)
       raise ArgumentError, "data_offset must be non-negative" if data_offset.negative?
       raise ArgumentError, "data_offset out of range" if data_offset > byte_size
@@ -29,6 +38,7 @@ module WGPU
       write_size = size.nil? ? (byte_size - data_offset) : Integer(size)
       raise ArgumentError, "size must be non-negative" if write_size.negative?
       raise ArgumentError, "data_offset + size out of range" if data_offset + write_size > byte_size
+      DataTypes.validate_alignment!(write_size, 4, name: "size")
 
       Native.wgpuQueueWriteBuffer(
         @handle,
@@ -39,8 +49,8 @@ module WGPU
       )
     end
 
-    def write_texture(destination:, data:, data_layout:, size:)
-      data_ptr, byte_size = data_to_pointer(data)
+    def write_texture(destination:, data:, data_layout:, size:, type: :f32)
+      data_ptr, byte_size = DataTypes.to_pointer(data, type:)
 
       dst = Native::ImageCopyTexture.new
       dst[:texture] = destination[:texture].handle
@@ -48,7 +58,11 @@ module WGPU
       dst[:origin][:x] = destination.dig(:origin, :x) || 0
       dst[:origin][:y] = destination.dig(:origin, :y) || 0
       dst[:origin][:z] = destination.dig(:origin, :z) || 0
-      dst[:aspect] = destination[:aspect] || :all
+      dst[:aspect] = Native::EnumHelper.coerce(
+        Native::TextureAspect,
+        destination[:aspect] || :all,
+        name: "texture aspect"
+      )
 
       extent = Native::Extent3D.new
       if size.is_a?(Array)
@@ -69,14 +83,13 @@ module WGPU
       Native.wgpuQueueWriteTexture(@handle, dst, data_ptr, byte_size, layout, extent)
     end
 
-    def read_buffer(buffer, offset: 0, size: nil, device:)
-      size ||= buffer.size - offset
-
-      staging = Buffer.new(device,
-        size: size,
-        usage: [:map_read, :copy_dst]
-      )
+    def read_buffer(buffer, offset: 0, size: nil, device: nil, staging: nil)
+      device ||= @device
+      raise ArgumentError, "device is required when the queue has no owning device" unless device
 
+      size ||= buffer.size - offset
+      owns_staging = staging.nil?
+      staging ||= Buffer.new(device, size: size, usage: [:map_read, :copy_dst])
       encoder = CommandEncoder.new(device)
       encoder.copy_buffer_to_buffer(
         source: buffer,
@@ -89,26 +102,40 @@ module WGPU
       submit([command_buffer])
 
       staging.map_sync(:read)
-      data = staging.read_mapped_data
-      staging.unmap
-      staging.release
-
-      data
+      staging.read_mapped_data(size:)
+    ensure
+      staging&.unmap if staging && staging.map_state == :mapped
+      command_buffer&.release
+      encoder&.release
+      staging&.release if owns_staging
     end
 
-    def read_texture(source:, data_layout:, size:, device:)
-      width = size[:width] || size[0]
-      height = size[:height] || size[1] || 1
-      depth = size[:depth_or_array_layers] || size[2] || 1
+    def read_texture(source:, data_layout:, size:, device: nil, staging: nil)
+      device ||= @device
+      raise ArgumentError, "device is required when the queue has no owning device" unless device
+
+      width, height, depth = texture_extent(size)
       bytes_per_row = data_layout[:bytes_per_row]
-      rows_per_image = data_layout[:rows_per_image] || height
-      buffer_size = bytes_per_row * rows_per_image * depth
+      raise ArgumentError, "data_layout[:bytes_per_row] is required" unless bytes_per_row
 
-      staging = Buffer.new(device,
-        size: buffer_size,
-        usage: [:map_read, :copy_dst]
+      DataTypes.validate_alignment!(
+        bytes_per_row,
+        TextureFormat::COPY_ALIGNMENT,
+        name: "bytes_per_row"
       )
+      format = source[:format] || source[:texture].format
+      aspect = source[:aspect] || :all
+      minimum_bytes_per_row = TextureFormat.bytes_per_row(width, format, aspect:)
+      if bytes_per_row < minimum_bytes_per_row
+        raise ArgumentError,
+          "bytes_per_row must be at least #{minimum_bytes_per_row} for width #{width} and #{format.inspect}"
+      end
+
+      rows_per_image = data_layout[:rows_per_image] || height
+      buffer_size = bytes_per_row * rows_per_image * depth
 
+      owns_staging = staging.nil?
+      staging ||= Buffer.new(device, size: buffer_size, usage: [:map_read, :copy_dst])
       encoder = CommandEncoder.new(device)
       encoder.copy_texture_to_buffer(
         source: source,
@@ -124,15 +151,17 @@ module WGPU
       submit([command_buffer])
 
       staging.map_sync(:read)
-      data = staging.read_mapped_data
-      staging.unmap
-      staging.release
-
-      data
+      staging.read_mapped_data(size: buffer_size)
+    ensure
+      staging&.unmap if staging && staging.map_state == :mapped
+      command_buffer&.release
+      encoder&.release
+      staging&.release if owns_staging
     end
 
-    def on_submitted_work_done(device: nil)
+    def on_submitted_work_done(device: nil, timeout: nil)
       device ||= @device
+      instance = device&.adapter&.instance
       status_holder = { done: false, status: nil }
 
       callback = FFI::Function.new(
@@ -144,28 +173,31 @@ module WGPU
 
       callback_info = Native::QueueWorkDoneCallbackInfo.new
       callback_info[:next_in_chain] = nil
-      callback_info[:mode] = 1
+      callback_info[:mode] = AsyncWaiter.callback_mode(instance: instance)
       callback_info[:callback] = callback
       callback_info[:userdata1] = nil
       callback_info[:userdata2] = nil
 
-      Native.wgpuQueueOnSubmittedWorkDone(@handle, callback_info)
-
-      if device
-        until status_holder[:done]
-          Native.wgpuDevicePoll(device.handle, 0, nil)
-          sleep(0.001)
-        end
-      else
-        sleep(0.001) until status_holder[:done]
+      callback_token = CallbackKeepalive.retain(self, callback)
+      begin
+        future = Native.wgpuQueueOnSubmittedWorkDone(@handle, callback_info)
+        AsyncWaiter.wait(
+          status_holder: status_holder,
+          instance: instance,
+          device: device,
+          future: future,
+          timeout: timeout
+        )
+      ensure
+        CallbackKeepalive.release(self, callback_token)
       end
 
       status_holder[:status]
     end
 
-    def on_submitted_work_done_async(device: nil)
+    def on_submitted_work_done_async(device: nil, timeout: nil)
       AsyncTask.new do
-        on_submitted_work_done(device: device)
+        on_submitted_work_done(device: device, timeout: timeout)
       end
     end
 
@@ -177,21 +209,13 @@ module WGPU
 
     private
 
-    def data_to_pointer(data)
-      case data
-      when String
-        ptr = FFI::MemoryPointer.new(:char, data.bytesize)
-        ptr.put_bytes(0, data)
-        [ptr, data.bytesize]
-      when Array
-        ptr = FFI::MemoryPointer.new(:float, data.size)
-        ptr.write_array_of_float(data)
-        [ptr, data.size * 4]
-      when FFI::Pointer
-        [data, data.size]
+    def texture_extent(size)
+      if size.is_a?(Array)
+        [size.fetch(0), size[1] || 1, size[2] || 1]
       else
-        raise ArgumentError, "Unsupported data type: #{data.class}"
+        [size.fetch(:width), size[:height] || 1, size[:depth_or_array_layers] || 1]
       end
     end
+
   end
 end

data/lib/wgpu/core/surface.rb

@@ -86,7 +86,7 @@ module WGPU
       config = Native::SurfaceConfiguration.new
       config[:next_in_chain] = nil
       config[:device] = device.handle
-      config[:format] = format
+      config[:format] = Native::EnumHelper.coerce(Native::TextureFormat, format, name: "surface format")
       config[:usage] = normalize_usage(usage)
       config[:width] = width
       config[:height] = height
@@ -95,15 +95,23 @@ module WGPU
         @view_formats_ptr = nil
         config[:view_formats] = nil
       else
-        format_values = view_formats.map do |vf|
-          vf.is_a?(Integer) ? vf : Native::TextureFormat[vf]
+        format_values = view_formats.map do |view_format|
+          Native::EnumHelper.coerce(Native::TextureFormat, view_format, name: "view format")
         end
         @view_formats_ptr = FFI::MemoryPointer.new(:uint32, format_values.size)
         @view_formats_ptr.write_array_of_uint32(format_values)
         config[:view_formats] = @view_formats_ptr
       end
-      config[:alpha_mode] = Native::CompositeAlphaMode[alpha_mode]
-      config[:present_mode] = Native::PresentMode[present_mode]
+      config[:alpha_mode] = Native::EnumHelper.coerce(
+        Native::CompositeAlphaMode,
+        alpha_mode,
+        name: "alpha mode"
+      )
+      config[:present_mode] = Native::EnumHelper.coerce(
+        Native::PresentMode,
+        present_mode,
+        name: "present mode"
+      )
 
       Native.wgpuSurfaceConfigure(@handle, config)
       @configured = true
@@ -134,7 +142,7 @@ module WGPU
 
       status = Native::SurfaceGetCurrentTextureStatus[surface_texture[:status]]
       unless status == :success_optimal || status == :success_suboptimal
-        raise SurfaceError, "Failed to get current texture: #{status}"
+        raise SurfaceAcquisitionError.new(status)
       end
 
       texture_ptr = surface_texture[:texture]
@@ -142,7 +150,7 @@ module WGPU
         raise SurfaceError, "Surface returned null texture"
       end
 
-      Texture.from_handle(texture_ptr)
+      Texture.from_handle(texture_ptr, surface_status: status)
     end
 
     def get_current_texture
@@ -206,16 +214,7 @@ module WGPU
     private
 
     def normalize_usage(usage)
-      case usage
-      when Integer
-        usage
-      when Symbol
-        Native::TextureUsage[usage]
-      when Array
-        usage.reduce(0) { |acc, u| acc | Native::TextureUsage[u] }
-      else
-        raise ArgumentError, "Invalid usage: #{usage}"
-      end
+      Native::EnumHelper.coerce_flags(Native::TextureUsage, usage, name: "surface usage")
     end
   end
 end